Docling is a document processing and parsing tool, created by IBM Research, and open sourced under the Linux Foundation. It was designed to convert unstructured documents into clean, readable data for AI-based workflows. We also offer Docling for IBM watsonx as a managed service, which helps developers deploy and use Docling even faster and easier. This article will show how to use Docling for IBM watsonx with Astra DB.
Astra DB is a serverless, distributed, NoSQL database built from the Apache Cassandra® project. It allows engineers to focus on building large-scale applications, without having to worry about database operations or maintenance.
Here we will show how to use the new Docling connector for Astra DB, which can be used to quickly ingest and parse documents for AI applications. First, we will show how to configure the required components, such as Astra DB and the Docling instance. Then we will show how to leverage Python to process documents through Docling and into Astra DB.
Requirements
Before proceeding, we need to make sure that (both) our local and cloud environments are properly set up. We will require:
-
An account with an embedding model provider (OpenAI, HuggingFace, Nvidia, etc) and that also has an API key generated.
Configuration
Getting this to work properly requires the coordination of a few different components. Here we will focus on Astra DB, the Docling service for IBM watsonx, and our environment variables for running a Python script locally.
Astra DB setup
This part assumes that you have an Astra DB account with a serverless, vector database (Figure 1). Log in at https://astra.datastax.com, select your Astra DB instance, and create a new keyspace named “docling.”
Figure 1 – Creating a new, serverless (vector) Astra database in Amazon Web Services (AWS).
Note: A database instance created on the Astra DB free tier will work just fine for this exercise.
Next, let’s create a new collection inside our docling keyspace. Name the collection “docling_docs,” and make sure that the “Vector-enabled collection” option is enabled. Click on the “Embedding generation method” and select the “plus” option to “Add embedding provider integration.” A new window should appear, similar to Figure 2.
Figure 2 – Defining a new embedding provider integration for HuggingFace (Serverless).
For this exercise, we will select “HuggingFace - Serverless,” give it a unique name (I will use my name “Aaron”), and paste-in our HuggingFace API token. Our docling_db database should be listed below and require nothing further. Next, click the “Add integration” button.
Back on the collection creation window (Figure 3), we should now see that we will be using “HuggingFace - Serverless” as our embedding generation method and our named user access token (“Aaron”) should be specified. Next, choose the “sentence-transformers/all-MiniLM-L6-v2" embedding model from the model drop-down. Finally, click the “Create collection” button.
Figure 3 – The collection creation window, showing that HuggingFace (serverless) has been added as our embedding generation method, and that we have selected the “all-MiniLM-L6-v2" embedding model.
If everything worked, the Data Explorer should now show our new docling_docs collection with the HuggingFace icon, the all-MiniLm-L6-v2 model name, 384 dimensions, and Cosine similarity showing zero (0) records. We can now move on to configure our Docling for IBM watsonx instance.
Note: Make a note of your Astra DB API endpoint and token.
Docling for IBM watsonx setup
We will start our free trial of Docling for IBM watsonx.data, by heading to https://www.ibm.com/products/docling in a browser and clicking on one of the blue “Free trial” buttons. Upon signing up, we can create our Docling for IBM watsonx instance. For this exercise, we will elect to build it on AWS.
From there, we should be taken to the IBM SaaS Console, where we can select our newly created instance. On the “Subscriptions” page, click on the “View instances” link. Then on the next page (Figure 4), look for your instance and click on the “Open” link to get to the workbench.
Figure 4 – Docling for IBM watsonx instance page, with the “Open” link in the lower right-hand corner.
Once the workbench opens, we can click on the “API examples” option (in the left navigation) to see our service URL (Figure 5). It should be at the top of the page.
Figure 5 – The “API examples” page on the Docling for IBM watsonx workbench, showing our Docling service URL.
Next, we will click on the “API keys” option, and then the “Generate key” button. We will then provide a unique name for the key and a future expiration date to generate a new API key.
Note: Make a note of your service URL endpoint and API key.
Environment variables
First, we will need to open up a terminal session. This is where we will run our Python script to test the connector. For Astra DB, we need to define four environment variables:
export ASTRA_KEYSPACE=docling
export ASTRA_COLLECTION=docling_docs
export ASTRA_API_ENDPOINT=https://70264115-7844-blah-blah-2970c5a937a9-us-east-2.apps.astra.datastax.com
export ASTRA_TOKEN=AstraCS:ftkFixrblahblahMUUWALz:0b1a0dbb7blahblah1ec0d
Next, we need to define two environment variables that are specific to Docling:
export DOCLING_SERVICE_URL=https://api.aws-c1.dcls.saas.ibm.com/20260813-1859-blah-blah-b34acee322c4
export DOCLING_API_KEY=azI6ZjM5YTI2NblahblahTd5akgwTkwwTmxDcmc9
With those variables defined, we should now be able to run our Python script.
Testing with Python
Note: Either clone the repository or copy that Python script down to your local system.
The docling_to_astra.py script defines three documents in a variable named WEB_SOURCES, as shown here:
WEB_SOURCES = [
"https://arxiv.org/pdf/2408.09869", # Docling paper
"https://arxiv.org/pdf/2501.17887", # DoclingV2 paper
"https://arxiv.org/pdf/2501.08828", # third example
]
The script sends each of these documents as a part of a batch request to our Docling for IBM watsonx instance. It then polls the batch task until it is complete. We can run the script with the following command:
python3 docling_to_astra.py
This script should download the three default web PDF documents, process them with the Docling connector, and write the results into Astra DB. The documents will be “chunked” into smaller records, each with vector embeddings.
We can monitor our job on the “Tasks” tab of the Docling for IBM watsonx workbench. Our task should be shown as “completed” with a green icon to indicate success. Additionally, our script should complete with a final status line of “success.”
Next, let’s go back to Astra DB and check out the Data Explorer. There should be 197 records present, as shown in Figure 6.
Figure 6 – Our docling_db Astra DB instance showing 197 records in our docling_docs collection.
In this article, we examined the IBM Docling connector for Astra DB. We showed how to properly configure a new collection in Astra DB to work with the Docling connector. Then we showed where to create our Docling for IBM watsonx instance, and how to get the connection credentials. We finally put it all together by defining our environment variables and running a script to process three web PDF documents through the connector.
If you run Astra DB and find yourself building an AI application and quickly need to ingest multiple documents to support retrieval augmented generation (RAG) or vector search, then you should check out the Docling connector. To get started, have a look at the Docling for IBM watsonx “Quickstart.” Of course, if you haven’t had a look at Astra DB, head on out to https://astra.datastax.com and sign up for a free account!
Links
#watsonx.data
#astradb