AstraDB
Write document chunks with embeddings to DataStax AstraDB vector database
AstraDB Connector
The AstraDB connector writes document chunks with vector embeddings to a DataStax AstraDB collection. Docling will chunk documents and AstraDB's server-side vectorization feature can generate embeddings, eliminating the need to manage your own embedding infrastructure.
Prerequisites
- AstraDB Account: Sign up at astra.datastax.com
- AstraDB Database: Create a vector-enabled database in your preferred region
- Application Token: Generate via AstraDB Console → Settings → Generate Token
- API Endpoint: Available in AstraDB Console under the "Connect" tab
Setup and Authentication
1. Create an AstraDB Database
- Log in to the AstraDB Console
- Click "Create Database"
- Choose "Serverless (vector)" as the database type
- Select your preferred region and tier
2. Generate Application Token
- Navigate to Account Settings → Tokens
- Select the appropriate role (Database Administrator recommended for write access)
- Click "Generate Token"
- Save the token securely (format:
AstraCS:...)
3. Get API Endpoint
- In the AstraDB Console, open your database
- Copy the API endpoint URL (format:
https://<database-id>-<region>.apps.astra.datastax.com)
4. Create the collection
The connector writes into an existing collection and does not create one. Create it before you run a batch job, with the same embedding provider and model that you set in the target:
- With your database open in the AstraDB Console, select "Create Collection"
- Enable vector search, and choose the embedding provider and model, for example NVIDIA and
nvidia/nv-embedqa-e5-v5
Or create it from Python with astrapy:
from astrapy import DataAPIClient
from astrapy.info import CollectionDefinition
database = DataAPIClient().get_database(api_endpoint, token=token)
if "docling_chunks" not in database.list_collection_names():
database.create_collection(
"docling_chunks",
definition=CollectionDefinition.builder()
.set_vector_service("nvidia", "nvidia/nv-embedqa-e5-v5")
.build(),
)Configuration
The AstraDB connector is used as a target in the Batch API. Configure it in the target field of your request.
Required Parameters
| Parameter | Type | Description |
|---|---|---|
kind | string | Must be "astradb_chunks" |
api_endpoint | string | AstraDB API endpoint URL from the Connect tab |
token | string | AstraDB application token (format: AstraCS:...) |
collection_name | string | Name of the collection to write chunks into |
Optional Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
keyspace | string | "default_keyspace" | AstraDB keyspace (namespace) to use |
vectorize_provider | string | "nvidia" | Embedding provider for server-side vectorization. Options: "openai", "huggingface", "nvidia", "voyageai" |
vectorize_model | string | "nvidia/nv-embedqa-e5-v5" | Model name for embeddings. Must be supported by the chosen provider |
vectorize_authentication | object | null | Authentication for the embedding provider. Example: {"providerKey": "OPENAI_API_KEY"} |
text_field | string | "text" | Field name for storing chunk text |
metadata_field | string | "metadata" | Field name for storing chunk metadata |
doc_id_field | string | "doc_id" | Field name for storing source document identifier |
chunk_index_field | string | "chunk_index" | Field name for storing chunk position in document |
page_field | string | - | Optional field name for page numbers |
headings_field | string | - | Optional field name for chunk headings |
coerce_large_ints_to_str | boolean | true | Convert large integers to strings to avoid overflow errors |
Vectorization Providers
AstraDB supports multiple embedding providers for server-side vectorization:
AstraDB hosts NVIDIA models as a default.
NVIDIA (default, Astra-hosted)
{
"vectorize_provider": "nvidia",
"vectorize_model": "nvidia/nv-embedqa-e5-v5"
}Available Models: nvidia/nv-embedqa-e5-v5, NV-Embed-QA
You can also use external embedding provider integrations. See the AstraDB Embedding Generation documentation for details.
OpenAI (external)
{
"vectorize_provider": "openai",
"vectorize_model": "text-embedding-3-small",
"vectorize_authentication": {
"providerKey": "OPENAI_API_KEY"
}
}Available Models: text-embedding-3-small, text-embedding-3-large, text-embedding-ada-002
HuggingFace (external)
{
"vectorize_provider": "huggingface",
"vectorize_model": "sentence-transformers/all-MiniLM-L6-v2",
"vectorize_authentication": {
"providerKey": "HUGGINGFACE_API_KEY"
}
}Available Models: BAAI/bge-base-en-v1.5, BAAI/bge-large-en-v1.5, BAAI/bge-small-en-v1.5, intfloat/multilingual-e5-large, intfloat/multilingual-e5-large-instruct, sentence-transformers/all-MiniLM-L6-v2
Connector-Specific Behavior
Existing collection required
The collection named in collection_name must exist (see Create the collection). If it does not, every chunk fails to upsert and the batch reports all documents as failed. Use the same vectorize_provider and vectorize_model in the target as in the collection.
Chunking Strategy
Documents are automatically chunked before being written to AstraDB. You can control chunking behavior using the options.chunking_options parameter in your batch request. Docling will attempt to fetch the tokenizer from HuggingFace. Default is "sentence-transformers/all-MiniLM-L6-v2".
{
"options": {
"chunking_options": {
"chunker": "hybrid",
"tokenizer": "intfloat/e5-large-unsupervised",
"max_tokens": 384
}
}
}Use the tokenizer of your embedding model, and keep max_tokens below the model's input limit. The chunk's headings are added to its text before embedding, so a chunk at the full limit is too long: AstraDB rejects it on upload. For nvidia/nv-embedqa-e5-v5 (512 tokens), 384 works.
Server-Side Embeddings
Embeddings are generated server-side by AstraDB using the configured vectorize_provider and vectorize_model. This means:
- No need to generate embeddings in your application
- Consistent embedding generation across all chunks
- Reduced data transfer (only text is sent, embeddings are computed in AstraDB)
Idempotent Writes
The connector uses upsert operations (update-or-insert) with a deterministic chunk ID generated from the document's binary hash, filename, and chunk index. Re-running the same batch job updates existing chunks rather than creating duplicates.
Large Integer Handling
AstraDB uses 64-bit signed integers. Documents may contain integers that exceed this range (e.g., DoclingDocument.origin.binary_hash). The connector automatically converts these to strings when coerce_large_ints_to_str is enabled (default).
Limitations
- Collection Creation: The connector does not create collections. Create the collection, with its embedding provider and model, before you run a batch job.
- Keyspace Must Exist: The specified keyspace must already exist in your database. The connector does not create keyspaces.
"default_keyspace"should exist, and is the fallback/default. - Chunk Size: Maximum chunk size depends on the embedding model's token limit. Keep
max_tokensin the chunking options below it, to leave room for the headings. - Rate Limits: AstraDB enforces rate limits based on your plan tier. Large batch jobs may need to be throttled. See the AstraDB Rate Limits documentation for details.
- Embedding Provider Limits: Server-side embedding generation is subject to the limits of your chosen provider (e.g., OpenAI rate limits).
Troubleshooting
"Failed to upsert chunk to AstraDB collection"
Causes:
- The collection does not exist. All documents fail, and the AstraDB console shows no collection
- Chunks exceed the maximum size for your embedding model. Some documents fail, or some of their chunks are missing
- The collection uses a different embedding provider or model than the target
Solutions:
- Create the collection first (see Create the collection)
- Reduce
max_tokensinchunking_options(try 384, or 256) - Verify the
tokenizersetting is compatible with your embedding model - Check that
vectorize_providerandvectorize_modelmatch the collection
Usage Examples
There are three main ways to interface with the connectors. All use the same underlying POST /v1/convert/source/batch endpoint.
Tasks UI
Navigate to the Tasks view and select "Create Task +". Select Batch as the task type (connectors use batch tasks, not single).
Fill in the fields as prompted. They should correspond to the fields gathered above (excluding 'kind').
REST API
curl -X POST "${DOCLING_SERVICE_URL}/v1/convert/source/batch" \
-H "X-Api-Key: ${DOCLING_SERVICE_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"sources": [
{
"kind": "s3",
"endpoint": "s3.us-east-1.amazonaws.com",
"access_key": "YOUR_ACCESS_KEY",
"secret_key": "YOUR_SECRET_KEY",
"bucket": "my-documents",
"key_prefix": "pdfs/",
"max_num_elements": 100
}
],
"target": {
"kind": "astradb_chunks",
"api_endpoint": "https://abc123-us-east1.apps.astra.datastax.com",
"token": "AstraCS:YOUR_TOKEN_HERE",
"keyspace": "default_keyspace",
"collection_name": "docling_chunks",
"vectorize_provider": "nvidia",
"vectorize_model": "nvidia/nv-embedqa-e5-v5"
},
"options": {
"to_formats": ["json"],
"chunking_options": {
"chunker": "hybrid",
"tokenizer": "intfloat/e5-large-unsupervised",
"max_tokens": 384
}
}
}'Python SDK
Python SDK Note: This connector is not included in the standard docling.datamodel.service package. When using the Python SDK, configure it using GenericTargetRequest with keyword arguments. You do not need to install docling-jobkit.
from docling.service_client import DoclingServiceClient
from docling.datamodel.service.chunking import HybridChunkerOptions
from docling.datamodel.service.options import ConvertDocumentsOptions
from docling.datamodel.service.requests import AnyHttpSourceRequest, GenericTargetRequest
import os
SERVICE_URL = os.getenv("DOCLING_SERVICE_URL")
API_KEY = os.getenv("DOCLING_SERVICE_API_KEY")
# Configure AstraDB target using GenericTargetRequest
target = GenericTargetRequest(
kind="astradb_chunks",
api_endpoint="https://abc123-us-east1.apps.astra.datastax.com",
token="AstraCS:YOUR_TOKEN_HERE",
keyspace="default_keyspace",
collection_name="docling_chunks",
vectorize_provider="nvidia",
vectorize_model="nvidia/nv-embedqa-e5-v5"
)
options = ConvertDocumentsOptions(
chunking_options=HybridChunkerOptions(
chunker="hybrid",
tokenizer="intfloat/e5-large-unsupervised",
max_tokens=384,
)
)
with DoclingServiceClient(url=SERVICE_URL, api_key=API_KEY) as client:
job = client.submit_batch(
sources=[
AnyHttpSourceRequest(url="https://example.com/doc1.pdf"),
AnyHttpSourceRequest(url="https://example.com/doc2.pdf"),
],
target=target,
options=options,
)
# Wait for completion
response = job.result()
print(f"Processed {response.num_converted} documents")
print(f"Succeeded: {response.num_succeeded}")
print(f"Failed: {response.num_failed}")Related Documentation
- Batch API Reference - Batch endpoint documentation
- Connectors Overview - All available connectors
- AstraDB Documentation - Official AstraDB documentation