Method: corpora.documents.create
Creates an empty Document
.
Endpoint
post https://generativelanguage.googleapis.com/v1beta/{parent=corpora/*}/documentsPath parameters
parent
string
Required. The name of the Corpus
where this Document
will be created. Example: corpora/my-corpus-123
It takes the form corpora/{corpora}
.
Request body
The request body contains an instance of Document
.
name
string
Immutable. Identifier. The Document
resource name. The ID (name excluding the "corpora/*/documents/" prefix) can contain up to 40 characters that are lowercase alphanumeric or dashes (-). The ID cannot start or end with a dash. If the name is empty on create, a unique name will be derived from displayName
along with a 12 character random suffix. Example: corpora/{corpus_id}/documents/my-awesome-doc-123a456b789c
displayName
string
Optional. The human-readable display name for the Document
. The display name must be no more than 512 characters in length, including spaces. Example: "Semantic Retriever Documentation"
Optional. User provided custom metadata stored as key-value pairs used for querying. A Document
can have a maximum of 20 CustomMetadata
.
Response body
If successful, the response body contains a newly created instance of Document
.
Method: corpora.documents.query
Performs semantic search over a Document
.
Endpoint
post https://generativelanguage.googleapis.com/v1beta/{name=corpora/*/documents/*}:queryPath parameters
name
string
Required. The name of the Document
to query. Example: corpora/my-corpus-123/documents/the-doc-abc
It takes the form corpora/{corpora}/documents/{document}
.
Request body
The request body contains data with the following structure:
query
string
Required. Query string to perform semantic search.
resultsCount
integer
Optional. The maximum number of Chunk
s to return. The service may return fewer Chunk
s.
If unspecified, at most 10 Chunk
s will be returned. The maximum specified result count is 100.
Optional. Filter for Chunk
metadata. Each MetadataFilter
object should correspond to a unique key. Multiple MetadataFilter
objects are joined by logical "AND"s.
Note: Document
-level filtering is not supported for this request because a Document
name is already specified.
Example query: (year >= 2020 OR year < 2010) AND (genre = drama OR genre = action)
MetadataFilter
object list: metadataFilters = [ {key = "chunk.custom_metadata.year" conditions = [{int_value = 2020, operation = GREATER_EQUAL}, {int_value = 2010, operation = LESS}}, {key = "chunk.custom_metadata.genre" conditions = [{stringValue = "drama", operation = EQUAL}, {stringValue = "action", operation = EQUAL}}]
Example query for a numeric range of values: (year > 2015 AND year <= 2020)
MetadataFilter
object list: metadataFilters = [ {key = "chunk.custom_metadata.year" conditions = [{int_value = 2015, operation = GREATER}]}, {key = "chunk.custom_metadata.year" conditions = [{int_value = 2020, operation = LESS_EQUAL}]}]
Note: "AND"s for the same key are only supported for numeric values. String values only support "OR"s for the same key.
Response body
Response from documents.query
containing a list of relevant chunks.
If successful, the response body contains data with the following structure:
The returned relevant chunks.
JSON representation |
---|
{
"relevantChunks": [
{
object ( |
Method: corpora.documents.list
Lists all Document
s in a Corpus
.
Endpoint
get https://generativelanguage.googleapis.com/v1beta/{parent=corpora/*}/documentsPath parameters
parent
string
Required. The name of the Corpus
containing Document
s. Example: corpora/my-corpus-123
It takes the form corpora/{corpora}
.
Query parameters
pageSize
integer
Optional. The maximum number of Document
s to return (per page). The service may return fewer Document
s.
If unspecified, at most 10 Document
s will be returned. The maximum size limit is 20 Document
s per page.
pageToken
string
Optional. A page token, received from a previous documents.list
call.
Provide the nextPageToken
returned in the response as an argument to the next request to retrieve the next page.
When paginating, all other parameters provided to documents.list
must match the call that provided the page token.
Request body
The request body must be empty.
Response body
Response from documents.list
containing a paginated list of Document
s. The Document
s are sorted by ascending document.create_time
.
If successful, the response body contains data with the following structure:
The returned Document
s.
nextPageToken
string
A token, which can be sent as pageToken
to retrieve the next page. If this field is omitted, there are no more pages.
JSON representation |
---|
{
"documents": [
{
object ( |
Method: corpora.documents.get
Gets information about a specific Document
.
Endpoint
get https://generativelanguage.googleapis.com/v1beta/{name=corpora/*/documents/*}Path parameters
name
string
Required. The name of the Document
to retrieve. Example: corpora/my-corpus-123/documents/the-doc-abc
It takes the form corpora/{corpora}/documents/{document}
.
Request body
The request body must be empty.
Response body
If successful, the response body contains an instance of Document
.
Method: corpora.documents.patch
Updates a Document
.
Endpoint
patch https://generativelanguage.googleapis.com/v1beta/{document.name=corpora/*/documents/*}PATCH https://generativelanguage.googleapis.com/v1beta/{document.name=corpora/*/documents/*}
Path parameters
document.name
string
Immutable. Identifier. The Document
resource name. The ID (name excluding the "corpora/*/documents/" prefix) can contain up to 40 characters that are lowercase alphanumeric or dashes (-). The ID cannot start or end with a dash. If the name is empty on create, a unique name will be derived from displayName
along with a 12 character random suffix. Example: corpora/{corpus_id}/documents/my-awesome-doc-123a456b789c
It takes the form corpora/{corpora}/documents/{document}
.
Query parameters
Required. The list of fields to update. Currently, this only supports updating displayName
and customMetadata
.
This is a comma-separated list of fully qualified names of fields. Example: "user.displayName,photo"
.
Request body
The request body contains an instance of Document
.
displayName
string
Optional. The human-readable display name for the Document
. The display name must be no more than 512 characters in length, including spaces. Example: "Semantic Retriever Documentation"
Optional. User provided custom metadata stored as key-value pairs used for querying. A Document
can have a maximum of 20 CustomMetadata
.
Response body
If successful, the response body contains an instance of Document
.
Method: corpora.documents.delete
Deletes a Document
.
Endpoint
delete https://generativelanguage.googleapis.com/v1beta/{name=corpora/*/documents/*}Path parameters
name
string
Required. The resource name of the Document
to delete. Example: corpora/my-corpus-123/documents/the-doc-abc
It takes the form corpora/{corpora}/documents/{document}
.
Query parameters
force
boolean
Optional. If set to true, any Chunk
s and objects related to this Document
will also be deleted.
If false (the default), a FAILED_PRECONDITION
error will be returned if Document
contains any Chunk
s.
Request body
The request body must be empty.
Response body
If successful, the response body is empty.
REST Resource: corpora.documents
Resource: Document
A Document
is a collection of Chunk
s. A Corpus
can have a maximum of 10,000 Document
s.
name
string
Immutable. Identifier. The Document
resource name. The ID (name excluding the "corpora/*/documents/" prefix) can contain up to 40 characters that are lowercase alphanumeric or dashes (-). The ID cannot start or end with a dash. If the name is empty on create, a unique name will be derived from displayName
along with a 12 character random suffix. Example: corpora/{corpus_id}/documents/my-awesome-doc-123a456b789c
displayName
string
Optional. The human-readable display name for the Document
. The display name must be no more than 512 characters in length, including spaces. Example: "Semantic Retriever Documentation"
Optional. User provided custom metadata stored as key-value pairs used for querying. A Document
can have a maximum of 20 CustomMetadata
.
Output only. The Timestamp of when the Document
was last updated.
A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z"
and "2014-10-02T15:01:23.045123456Z"
.
Output only. The Timestamp of when the Document
was created.
A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z"
and "2014-10-02T15:01:23.045123456Z"
.
JSON representation |
---|
{
"name": string,
"displayName": string,
"customMetadata": [
{
object ( |
CustomMetadata
User provided metadata stored as key-value pairs.
key
string
Required. The key of the metadata to store.
Union field value
.
value
can be only one of the following:
stringValue
string
The string value of the metadata to store.
The StringList value of the metadata to store.
numericValue
number
The numeric value of the metadata to store.
JSON representation |
---|
{ "key": string, // Union field |
StringList
User provided string values assigned to a single metadata key.
values[]
string
The string values of the metadata to store.
JSON representation |
---|
{ "values": [ string ] } |