DoclingDocling for IBM watsonx
Connectors

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

  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 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:

  1. With your database open in the AstraDB Console, select "Create Collection"
  2. 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

ParameterTypeDescription
kindstringMust be "astradb_chunks"
api_endpointstringAstraDB API endpoint URL from the Connect tab
tokenstringAstraDB application token (format: AstraCS:...)
collection_namestringName of the collection to write chunks into

Optional Parameters

ParameterTypeDefaultDescription
keyspacestring"default_keyspace"AstraDB keyspace (namespace) to use
vectorize_providerstring"nvidia"Embedding provider for server-side vectorization. Options: "openai", "huggingface", "nvidia", "voyageai"
vectorize_modelstring"nvidia/nv-embedqa-e5-v5"Model name for embeddings. Must be supported by the chosen provider
vectorize_authenticationobjectnullAuthentication for the embedding provider. Example: {"providerKey": "OPENAI_API_KEY"}
text_fieldstring"text"Field name for storing chunk text
metadata_fieldstring"metadata"Field name for storing chunk metadata
doc_id_fieldstring"doc_id"Field name for storing source document identifier
chunk_index_fieldstring"chunk_index"Field name for storing chunk position in document
page_fieldstring-Optional field name for page numbers
headings_fieldstring-Optional field name for chunk headings
coerce_large_ints_to_strbooleantrueConvert 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_tokens in 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:

  1. Create the collection first (see Create the collection)
  2. Reduce max_tokens in chunking_options (try 384, or 256)
  3. Verify the tokenizer setting is compatible with your embedding model
  4. Check that vectorize_provider and vectorize_model match 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}")

On this page