Connect with the Python client
You can connect to your Serverless (Vector) databases with the astrapy client.
|
For a guided experience to get started with the Python client, see the Astra DB Serverless quickstart. |
Prerequisites
-
An active Astra account
-
An active Serverless (Vector) database
Install the Python client
Install the Python client with pip:
-
Verify that pip is version 23.0 or later:
pip --version -
If needed, upgrade pip:
python -m pip install --upgrade pip -
Install the astrapy package
. You must have Python 3.9 or later.
pip install astrapy
Upgrade the Python client
When a new client version is released, upgrade your client to get the latest features, improvements, and bug fixes. For information about major changes in specific client versions, see Data API client upgrade guide.
# verbose
pip install astrapy --upgrade
# shorthand
pip install -U astrapySet environment variables
The Data API requires your database’s API endpoint and application tokens with sufficient permissions to perform the requested operations.
Store application tokens and API endpoints in environment variables to simplify reuse in your scripts.
-
In the Astra Portal navigation menu, select your Serverless (Vector) database.
-
On the Overview tab, in the Database Details section, click Generate Token.
The generated token has a custom Database Administrator role that is scoped to this database only. For more information, see Generate an application token for a database and Custom roles.
-
Copy the token and store it securely. The Astra Portal shows the token only once.
-
In the Database Details section, copy your database’s Data API endpoint.
The Data API endpoint format is
https://DATABASE_ID-REGION.apps.astra.datastax.com. If you aren’t using a client, be aware that DevOps API calls use a different endpoint format. -
(Optional) Create application tokens with other roles.
The Database Administrator role authorizes operations within a database, but you might need a broader or narrower role for other operations, for example:
-
For operations above the database level, such as creating databases or keyspaces, you need an application token with the Organization Administrator role.
-
For production applications that only read data from a database, consider using an application token with a narrower scope, such as the Read Only User role.
-
-
Set environment variables for your application tokens and Data API endpoint.
-
Linux or macOS
-
Windows
export ASTRA_DB_API_ENDPOINT=API_ENDPOINT export ASTRA_DB_APPLICATION_TOKEN=TOKENset ASTRA_DB_API_ENDPOINT=API_ENDPOINTset ASTRA_DB_APPLICATION_TOKEN=TOKEN -
Connect to a Serverless (Vector) database
When you use a Data API client, your main entry point is the DataAPIClient object.
Then, you get a database object to connect to a database.
These operations are the basis of your client scripts.
For more information, see Instantiate a client object and Connect to a database.
import os
from astrapy import DataAPIClient
from astrapy.constants import VectorMetric
# Initialize the client and get a "Database" object
client = DataAPIClient(os.environ["ASTRA_DB_APPLICATION_TOKEN"])
database = client.get_database(os.environ["ASTRA_DB_API_ENDPOINT"])
print(f"* Database: {database.info().name}\n")Next steps
After you connect to a database, you can extend your script to work with the collections and documents in it. You can also use the Python client to manage databases and keyspaces.
For more information, see Get started with the Data API and Python client usage.
