Skip to main content

Refresh External Collection (V2)

This operation triggers an asynchronous data refresh job for an existing external collection, re-syncing the collection's data from its underlying external source. externalSource and externalSpec must be both provided or both omitted; when both are omitted, the collection's previously persisted source and spec are reused.

POST/v2/vectordb/jobs/external_collection/refresh
Connection Endpoint

The base URL for this API is in the following format:

https://{cluster-id}.{region}.vectordb.zillizcloud.com:19530

📘Notes
  • Use the cluster endpoint if you are using serving clusters.

    • Free & Serverless

      https://{cluster-id}.serverless.{region}.vectordb.zillizcloud.com

    • Dedicated

      https://{cluster-id}.{region}.vectordb.zillizcloud.com:19530

The endpoints on the control plane currently supports up to 20 requests per second per user per endpoint.

export CLUSTER_ENDPOINT="https://{cluster-id}.{region}.vectordb.zillizcloud.com:19530"
Parameters
Authorizationstringheaderrequired

The authentication token should be an API key with appropriate privileges or a pair of colon-joined username and password, like username:password. If you are using a project endpoint, only a valid API key with sufficient permissions applies.

Example Value: Bearer {{TOKEN}}
Request Bodyapplication/json
dbNamestring

The name of the database.

collectionNamestringrequired

The name of the collection to refresh.

externalSourcestring

JSON-encoded specification of the external data source. When provided, externalSpec must also be provided. When omitted, the collection's persisted source is reused. An object url in a Zilliz Cloud volume applies.
This parameters applies only to Iceberg tables.

externalSpecstring

JSON-encoded specification describing how the external data maps to the collection. When provided, externalSource must also be provided. When omitted, the collection's persisted spec is reused.
This parameters applies only to Iceberg tables.

export TOKEN="YOUR_API_KEY"

curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/jobs/external_collection/refresh" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
-d '{
    "dbName": "default",
    "collectionName": "ext_books"
}'
Responses200 - application/json
codeinteger

Response code.

Example Value: 0
dataobject

Response payload carrying the new refresh job's identifier.

jobIdinteger<int64>

ID of the newly created refresh job. Use this value to query progress via the describe endpoint.

Returns an error message.

codeinteger

Response code.

messagestring

Error message.

{
    "code": 0,
    "data": {
        "jobId": 449503829274509300
    }
}