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

1. Log in to the AstraDB Console
2. Click "Create Database"
3. Choose "Serverless (vector)" as the database type
4. Select your preferred region and tier

2. Generate Application Token

1. Navigate to Account Settings → Tokens
2. Select the appropriate role (Database Administrator recommended for write access)
3. Click "Generate Token"
4. Save the token securely (format: AstraCS:...)

3. Get API Endpoint

1. In the AstraDB Console, open your database
2. Copy the API endpoint URL (format: https://<database-id>-<region>.apps.astra.datastax.com)

4. Create Collection

1. With your database open in the AstraDB Console, select "Create Collection"
2. Here you can choose your embeddings/vectorization provider and model. Take note of the model's dimensions

Note: This step is partly optional. If no collection exists, the connector will try to create one using the collection_name and vectorization settings provided.

Configuration

The AstraDB connector is used as a target in the Batch API. Configure it in the target field of your request.

Required Parameters

Optional Parameters

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

Automatic Collection Creation

If the specified collection does not exist, the connector automatically creates it with the configured vectorization settings. Existing collections are reused.

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": 512
    }
  }
}

The tokenizer should match the embedding model dimensions for optimal results. AstraDB will reject oversized chunks on upload.

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: Collections are created with default vectorization settings. For custom collection configurations (dimension size, similarity metric), create the collection manually in the AstraDB Console before running your 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. Ensure max_tokens in chunking options matches your model's capacity.
• 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:

• Chunks exceed the maximum size for your embedding model
• Token count in chunking options is too high

Solutions:

1. Reduce max_tokens in chunking_options (try 256 or 384)
2. Verify the tokenizer setting is compatible with your embedding model
3. Check AstraDB collection configuration for maximum document size limits

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').

Screenshots for this connector will be added here.

REST API

curl -X POST "${DOCLING_SERVICE_URL}/v1/convert/source/batch" \
  -H "X-Api-Key: ${DOCLING_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": 512
      }
    }
  }'

Python SDK

from docling.service_client import DoclingServiceClient
from docling.datamodel.service.requests import AnyHttpSourceRequest, S3SourceRequest, GenericTargetRequest
import os

SERVICE_URL = os.getenv("DOCLING_SERVICE_URL")
API_KEY = os.getenv("DOCLING_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"
)

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,
        output_formats=[OutputFormat.JSON]
    )
    
    # 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