# Chunks ## Method: corpora.documents.chunks.create - [Endpoint](https://ai.google.dev/api/semantic-retrieval/chunks#body.HTTP_TEMPLATE) - [Path parameters](https://ai.google.dev/api/semantic-retrieval/chunks#body.PATH_PARAMETERS) - [Request body](https://ai.google.dev/api/semantic-retrieval/chunks#body.request_body) - [Response body](https://ai.google.dev/api/semantic-retrieval/chunks#body.response_body) - [Authorization scopes](https://ai.google.dev/api/semantic-retrieval/chunks#body.aspect) Creates a `Chunk`. ### Endpoint post `https:``/``/generativelanguage.googleapis.com``/v1beta``/{parent=corpora``/*``/documents``/*}``/chunks` ### Path parameters `parent` `string` Required. The name of the `Document` where this `Chunk` will be created. Example: `corpora/my-corpus-123/documents/the-doc-abc` It takes the form `corpora/{corpora}/documents/{document}`. ### Request body The request body contains an instance of [Chunk](https://ai.google.dev/api/semantic-retrieval/chunks#Chunk). Fields `name` `string` Immutable. Identifier. The `Chunk` resource name. The ID (name excluding the "corpora/\*/documents/\*/chunks/" 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 random 12-character unique ID will be generated. Example: `corpora/{corpus_id}/documents/{document_id}/chunks/123a456b789c` `data` `object (`[ChunkData](https://ai.google.dev/api/semantic-retrieval/chunks#ChunkData)`)` Required. The content for the `Chunk`, such as the text string. The maximum number of tokens per chunk is 2043. `customMetadata[]` `object (`[CustomMetadata](https://ai.google.dev/api/semantic-retrieval/documents#v1beta.CustomMetadata)`)` Optional. User provided custom metadata stored as key-value pairs. The maximum number of `CustomMetadata` per chunk is 20. ### Response body If successful, the response body contains a newly created instance of [Chunk](https://ai.google.dev/api/semantic-retrieval/chunks#Chunk). ## Method: corpora.documents.chunks.list - [Endpoint](https://ai.google.dev/api/semantic-retrieval/chunks#body.HTTP_TEMPLATE) - [Path parameters](https://ai.google.dev/api/semantic-retrieval/chunks#body.PATH_PARAMETERS) - [Query parameters](https://ai.google.dev/api/semantic-retrieval/chunks#body.QUERY_PARAMETERS) - [Request body](https://ai.google.dev/api/semantic-retrieval/chunks#body.request_body) - [Response body](https://ai.google.dev/api/semantic-retrieval/chunks#body.response_body) - [JSON representation](https://ai.google.dev/api/semantic-retrieval/chunks#body.ListChunksResponse.SCHEMA_REPRESENTATION) - [Authorization scopes](https://ai.google.dev/api/semantic-retrieval/chunks#body.aspect) Lists all `Chunk`s in a `Document`. ### Endpoint get `https:``/``/generativelanguage.googleapis.com``/v1beta``/{parent=corpora``/*``/documents``/*}``/chunks` ### Path parameters `parent` `string` Required. The name of the `Document` containing `Chunk`s. Example: `corpora/my-corpus-123/documents/the-doc-abc` It takes the form `corpora/{corpora}/documents/{document}`. ### Query parameters `pageSize` `integer` Optional. The maximum number of `Chunk`s to return (per page). The service may return fewer `Chunk`s. If unspecified, at most 10 `Chunk`s will be returned. The maximum size limit is 100 `Chunk`s per page. `pageToken` `string` Optional. A page token, received from a previous `chunks.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 `chunks.list` must match the call that provided the page token. ### Request body The request body must be empty. ### Response body Response from `chunks.list` containing a paginated list of `Chunk`s. The `Chunk`s are sorted by ascending `chunk.create_time`. If successful, the response body contains data with the following structure: Fields `chunks[]` `object (`[Chunk](https://ai.google.dev/api/semantic-retrieval/chunks#Chunk)`)` The returned `Chunk`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 | |---------------------------------------------------------------------------------------------------------------------------| | ``` { "chunks": [ { object (https://ai.google.dev/api/semantic-retrieval/chunks#Chunk) } ], "nextPageToken": string } ``` | ## Method: corpora.documents.chunks.get - [Endpoint](https://ai.google.dev/api/semantic-retrieval/chunks#body.HTTP_TEMPLATE) - [Path parameters](https://ai.google.dev/api/semantic-retrieval/chunks#body.PATH_PARAMETERS) - [Request body](https://ai.google.dev/api/semantic-retrieval/chunks#body.request_body) - [Response body](https://ai.google.dev/api/semantic-retrieval/chunks#body.response_body) - [Authorization scopes](https://ai.google.dev/api/semantic-retrieval/chunks#body.aspect) Gets information about a specific `Chunk`. ### Endpoint get `https:``/``/generativelanguage.googleapis.com``/v1beta``/{name=corpora``/*``/documents``/*``/chunks``/*}` ### Path parameters `name` `string` Required. The name of the `Chunk` to retrieve. Example: `corpora/my-corpus-123/documents/the-doc-abc/chunks/some-chunk` It takes the form `corpora/{corpora}/documents/{document}/chunks/{chunk}`. ### Request body The request body must be empty. ### Response body If successful, the response body contains an instance of [Chunk](https://ai.google.dev/api/semantic-retrieval/chunks#Chunk). ## Method: corpora.documents.chunks.patch - [Endpoint](https://ai.google.dev/api/semantic-retrieval/chunks#body.HTTP_TEMPLATE) - [Path parameters](https://ai.google.dev/api/semantic-retrieval/chunks#body.PATH_PARAMETERS) - [Query parameters](https://ai.google.dev/api/semantic-retrieval/chunks#body.QUERY_PARAMETERS) - [Request body](https://ai.google.dev/api/semantic-retrieval/chunks#body.request_body) - [Response body](https://ai.google.dev/api/semantic-retrieval/chunks#body.response_body) - [Authorization scopes](https://ai.google.dev/api/semantic-retrieval/chunks#body.aspect) Updates a `Chunk`. ### Endpoint patch `https:``/``/generativelanguage.googleapis.com``/v1beta``/{chunk.name=corpora``/*``/documents``/*``/chunks``/*}` `PATCH https://generativelanguage.googleapis.com/v1beta/{chunk.name=corpora/*/documents/*/chunks/*}` ### Path parameters `chunk.name` `string` Immutable. Identifier. The `Chunk` resource name. The ID (name excluding the "corpora/\*/documents/\*/chunks/" 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 random 12-character unique ID will be generated. Example: `corpora/{corpus_id}/documents/{document_id}/chunks/123a456b789c` It takes the form `corpora/{corpora}/documents/{document}/chunks/{chunk}`. ### Query parameters `updateMask` `string (`[FieldMask](https://protobuf.dev/reference/protobuf/google.protobuf/#field-mask)` format)` Required. The list of fields to update. Currently, this only supports updating `customMetadata` and `data`. 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 [Chunk](https://ai.google.dev/api/semantic-retrieval/chunks#Chunk). Fields `data` `object (`[ChunkData](https://ai.google.dev/api/semantic-retrieval/chunks#ChunkData)`)` Required. The content for the `Chunk`, such as the text string. The maximum number of tokens per chunk is 2043. `customMetadata[]` `object (`[CustomMetadata](https://ai.google.dev/api/semantic-retrieval/documents#v1beta.CustomMetadata)`)` Optional. User provided custom metadata stored as key-value pairs. The maximum number of `CustomMetadata` per chunk is 20. ### Response body If successful, the response body contains an instance of [Chunk](https://ai.google.dev/api/semantic-retrieval/chunks#Chunk). ## Method: corpora.documents.chunks.delete - [Endpoint](https://ai.google.dev/api/semantic-retrieval/chunks#body.HTTP_TEMPLATE) - [Path parameters](https://ai.google.dev/api/semantic-retrieval/chunks#body.PATH_PARAMETERS) - [Request body](https://ai.google.dev/api/semantic-retrieval/chunks#body.request_body) - [Response body](https://ai.google.dev/api/semantic-retrieval/chunks#body.response_body) - [Authorization scopes](https://ai.google.dev/api/semantic-retrieval/chunks#body.aspect) Deletes a `Chunk`. ### Endpoint delete `https:``/``/generativelanguage.googleapis.com``/v1beta``/{name=corpora``/*``/documents``/*``/chunks``/*}` ### Path parameters `name` `string` Required. The resource name of the `Chunk` to delete. Example: `corpora/my-corpus-123/documents/the-doc-abc/chunks/some-chunk` It takes the form `corpora/{corpora}/documents/{document}/chunks/{chunk}`. ### Request body The request body must be empty. ### Response body If successful, the response body is an empty JSON object. ## Method: corpora.documents.chunks.batchCreate - [Endpoint](https://ai.google.dev/api/semantic-retrieval/chunks#body.HTTP_TEMPLATE) - [Path parameters](https://ai.google.dev/api/semantic-retrieval/chunks#body.PATH_PARAMETERS) - [Request body](https://ai.google.dev/api/semantic-retrieval/chunks#body.request_body) - [JSON representation](https://ai.google.dev/api/semantic-retrieval/chunks#body.request_body.SCHEMA_REPRESENTATION) - [Response body](https://ai.google.dev/api/semantic-retrieval/chunks#body.response_body) - [JSON representation](https://ai.google.dev/api/semantic-retrieval/chunks#body.BatchCreateChunksResponse.SCHEMA_REPRESENTATION) - [Authorization scopes](https://ai.google.dev/api/semantic-retrieval/chunks#body.aspect) - [CreateChunkRequest](https://ai.google.dev/api/semantic-retrieval/chunks#CreateChunkRequest) - [JSON representation](https://ai.google.dev/api/semantic-retrieval/chunks#CreateChunkRequest.SCHEMA_REPRESENTATION) Batch create `Chunk`s. ### Endpoint post `https:``/``/generativelanguage.googleapis.com``/v1beta``/{parent=corpora``/*``/documents``/*}``/chunks:batchCreate` ### Path parameters `parent` `string` Optional. The name of the `Document` where this batch of `Chunk`s will be created. The parent field in every `CreateChunkRequest` must match this value. 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: Fields `requests[]` `object (`[CreateChunkRequest](https://ai.google.dev/api/semantic-retrieval/chunks#CreateChunkRequest)`)` Required. The request messages specifying the `Chunk`s to create. A maximum of 100 `Chunk`s can be created in a batch. ### Response body Response from `chunks.batchCreate` containing a list of created `Chunk`s. If successful, the response body contains data with the following structure: Fields `chunks[]` `object (`[Chunk](https://ai.google.dev/api/semantic-retrieval/chunks#Chunk)`)` `Chunk`s created. | JSON representation | |--------------------------------------------------------------------------------------------------| | ``` { "chunks": [ { object (https://ai.google.dev/api/semantic-retrieval/chunks#Chunk) } ] } ``` | ## CreateChunkRequest Request to create a `Chunk`. Fields `parent` `string` Required. The name of the `Document` where this `Chunk` will be created. Example: `corpora/my-corpus-123/documents/the-doc-abc` `chunk` `object (`[Chunk](https://ai.google.dev/api/semantic-retrieval/chunks#Chunk)`)` Required. The `Chunk` to create. | JSON representation | |---------------------------------------------------------------------------------------------------------------| | ``` { "parent": string, "chunk": { object (https://ai.google.dev/api/semantic-retrieval/chunks#Chunk) } } ``` | ## Method: corpora.documents.chunks.batchUpdate - [Endpoint](https://ai.google.dev/api/semantic-retrieval/chunks#body.HTTP_TEMPLATE) - [Path parameters](https://ai.google.dev/api/semantic-retrieval/chunks#body.PATH_PARAMETERS) - [Request body](https://ai.google.dev/api/semantic-retrieval/chunks#body.request_body) - [JSON representation](https://ai.google.dev/api/semantic-retrieval/chunks#body.request_body.SCHEMA_REPRESENTATION) - [Response body](https://ai.google.dev/api/semantic-retrieval/chunks#body.response_body) - [JSON representation](https://ai.google.dev/api/semantic-retrieval/chunks#body.BatchUpdateChunksResponse.SCHEMA_REPRESENTATION) - [Authorization scopes](https://ai.google.dev/api/semantic-retrieval/chunks#body.aspect) - [UpdateChunkRequest](https://ai.google.dev/api/semantic-retrieval/chunks#UpdateChunkRequest) - [JSON representation](https://ai.google.dev/api/semantic-retrieval/chunks#UpdateChunkRequest.SCHEMA_REPRESENTATION) Batch update `Chunk`s. ### Endpoint post `https:``/``/generativelanguage.googleapis.com``/v1beta``/{parent=corpora``/*``/documents``/*}``/chunks:batchUpdate` ### Path parameters `parent` `string` Optional. The name of the `Document` containing the `Chunk`s to update. The parent field in every `UpdateChunkRequest` must match this value. 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: Fields `requests[]` `object (`[UpdateChunkRequest](https://ai.google.dev/api/semantic-retrieval/chunks#UpdateChunkRequest)`)` Required. The request messages specifying the `Chunk`s to update. A maximum of 100 `Chunk`s can be updated in a batch. ### Response body Response from `chunks.batchUpdate` containing a list of updated `Chunk`s. If successful, the response body contains data with the following structure: Fields `chunks[]` `object (`[Chunk](https://ai.google.dev/api/semantic-retrieval/chunks#Chunk)`)` `Chunk`s updated. | JSON representation | |--------------------------------------------------------------------------------------------------| | ``` { "chunks": [ { object (https://ai.google.dev/api/semantic-retrieval/chunks#Chunk) } ] } ``` | ## UpdateChunkRequest Request to update a `Chunk`. Fields `chunk` `object (`[Chunk](https://ai.google.dev/api/semantic-retrieval/chunks#Chunk)`)` Required. The `Chunk` to update. `updateMask` `string (`[FieldMask](https://protobuf.dev/reference/protobuf/google.protobuf/#field-mask)` format)` Required. The list of fields to update. Currently, this only supports updating `customMetadata` and `data`. This is a comma-separated list of fully qualified names of fields. Example: `"user.displayName,photo"`. | JSON representation | |-------------------------------------------------------------------------------------------------------------------| | ``` { "chunk": { object (https://ai.google.dev/api/semantic-retrieval/chunks#Chunk) }, "updateMask": string } ``` | ## Method: corpora.documents.chunks.batchDelete - [Endpoint](https://ai.google.dev/api/semantic-retrieval/chunks#body.HTTP_TEMPLATE) - [Path parameters](https://ai.google.dev/api/semantic-retrieval/chunks#body.PATH_PARAMETERS) - [Request body](https://ai.google.dev/api/semantic-retrieval/chunks#body.request_body) - [JSON representation](https://ai.google.dev/api/semantic-retrieval/chunks#body.request_body.SCHEMA_REPRESENTATION) - [Response body](https://ai.google.dev/api/semantic-retrieval/chunks#body.response_body) - [Authorization scopes](https://ai.google.dev/api/semantic-retrieval/chunks#body.aspect) - [DeleteChunkRequest](https://ai.google.dev/api/semantic-retrieval/chunks#DeleteChunkRequest) - [JSON representation](https://ai.google.dev/api/semantic-retrieval/chunks#DeleteChunkRequest.SCHEMA_REPRESENTATION) Batch delete `Chunk`s. ### Endpoint post `https:``/``/generativelanguage.googleapis.com``/v1beta``/{parent=corpora``/*``/documents``/*}``/chunks:batchDelete` ### Path parameters `parent` `string` Optional. The name of the `Document` containing the `Chunk`s to delete. The parent field in every `DeleteChunkRequest` must match this value. 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: Fields `requests[]` `object (`[DeleteChunkRequest](https://ai.google.dev/api/semantic-retrieval/chunks#DeleteChunkRequest)`)` Required. The request messages specifying the `Chunk`s to delete. ### Response body If successful, the response body is an empty JSON object. ## DeleteChunkRequest Request to delete a `Chunk`. Fields `name` `string` Required. The resource name of the `Chunk` to delete. Example: `corpora/my-corpus-123/documents/the-doc-abc/chunks/some-chunk` | JSON representation | |----------------------------| | ``` { "name": string } ``` | ## REST Resource: corpora.documents.chunks - [Resource: Chunk](https://ai.google.dev/api/semantic-retrieval/chunks#Chunk) - [JSON representation](https://ai.google.dev/api/semantic-retrieval/chunks#Chunk.SCHEMA_REPRESENTATION) - [ChunkData](https://ai.google.dev/api/semantic-retrieval/chunks#ChunkData) - [JSON representation](https://ai.google.dev/api/semantic-retrieval/chunks#ChunkData.SCHEMA_REPRESENTATION) - [State](https://ai.google.dev/api/semantic-retrieval/chunks#State) - [Methods](https://ai.google.dev/api/semantic-retrieval/chunks#METHODS_SUMMARY) ## Resource: Chunk A `Chunk` is a subpart of a `Document` that is treated as an independent unit for the purposes of vector representation and storage. A `Corpus` can have a maximum of 1 million `Chunk`s. Fields `name` `string` Immutable. Identifier. The `Chunk` resource name. The ID (name excluding the "corpora/\*/documents/\*/chunks/" 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 random 12-character unique ID will be generated. Example: `corpora/{corpus_id}/documents/{document_id}/chunks/123a456b789c` `data` `object (`[ChunkData](https://ai.google.dev/api/semantic-retrieval/chunks#ChunkData)`)` Required. The content for the `Chunk`, such as the text string. The maximum number of tokens per chunk is 2043. `customMetadata[]` `object (`[CustomMetadata](https://ai.google.dev/api/semantic-retrieval/documents#v1beta.CustomMetadata)`)` Optional. User provided custom metadata stored as key-value pairs. The maximum number of `CustomMetadata` per chunk is 20. `createTime` `string (`[Timestamp](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp)` format)` Output only. The Timestamp of when the `Chunk` was created. Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: `"2014-10-02T15:01:23Z"`, `"2014-10-02T15:01:23.045123456Z"` or `"2014-10-02T15:01:23+05:30"`. `updateTime` `string (`[Timestamp](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp)` format)` Output only. The Timestamp of when the `Chunk` was last updated. Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: `"2014-10-02T15:01:23Z"`, `"2014-10-02T15:01:23.045123456Z"` or `"2014-10-02T15:01:23+05:30"`. `state` `enum (`[State](https://ai.google.dev/api/semantic-retrieval/chunks#State)`)` Output only. Current state of the `Chunk`. | JSON representation | |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ``` { "name": string, "data": { object (https://ai.google.dev/api/semantic-retrieval/chunks#ChunkData) }, "customMetadata": [ { object (https://ai.google.dev/api/semantic-retrieval/documents#v1beta.CustomMetadata) } ], "createTime": string, "updateTime": string, "state": enum (https://ai.google.dev/api/semantic-retrieval/chunks#State) } ``` | ## ChunkData Extracted data that represents the `Chunk` content. Fields `data` `Union type` `data` can be only one of the following: `stringValue` `string` The `Chunk` content as a string. The maximum number of tokens per chunk is 2043. | JSON representation | |---------------------------------------------------------| | ``` { // data "stringValue": string // Union type } ``` | ## State States for the lifecycle of a `Chunk`. | Enums || |----------------------------|----------------------------------------------------------------| | `STATE_UNSPECIFIED` | The default value. This value is used if the state is omitted. | | `STATE_PENDING_PROCESSING` | `Chunk` is being processed (embedding and vector storage). | | `STATE_ACTIVE` | `Chunk` is processed and available for querying. | | `STATE_FAILED` | `Chunk` failed processing. |