Quickstart: Azure Cosmos DB for Apache Cassandra client library for Python

Get started with the Azure Cosmos DB for Apache Cassandra client library for Python to store, manage, and query unstructured data. Follow the steps in this guide to create a new account, install a Python client library, connect to the account, perform common operations, and query your final sample data.

API reference documentation | Library source code | Package (PyPI)

• An Azure subscription

  • If you don't have an Azure subscription, create a free account before you begin.

• The latest version of the Azure CLI in Azure Cloud Shell.

  • If you prefer to run CLI reference commands locally, sign in to the Azure CLI by using the az login command.

• Python 3.12 or later

First, set up the account and development environment for this guide. This section walks you through the process of creating an account, getting its credentials, and then preparing your development environment.

Start by creating an API for Apache Cassandra account. Once the account is created, create the keyspace and table resources.

Now, get the password for the client library to use to create a connection to the recently created account.

Then, configure your development environment with a new project and the client library. This step is the last required prerequisite before moving on to the rest of this guide.

1. Start in an empty directory.

2. Import the cassandra-driver package from the Python Package Index (PyPI).

   pip install cassandra-driver
   

3. Create the app.py file.

• Authenticate client
• Upsert data
• Read data
• Query data

Start by authenticating the client using the credentials gathered earlier in this guide.

1. Open the app.py file in your integrated development environment (IDE).

2. Import the following types from the cassandra-driver module:

   • cassandra.cluster.Cluster
   • cassandra.auth.PlainTextAuthProvider

   from cassandra.cluster import Cluster
   from cassandra.auth import PlainTextAuthProvider
   

3. Import the following types from the ssl module:

   • ssl.PROTOCOL_TLS_CLIENT
   • ssl.SSLContext
   • ssl.CERT_NONE

   from ssl import PROTOCOL_TLS_CLIENT, SSLContext, CERT_NONE
   

4. Create string variables for the credentials collected earlier in this guide. Name the variables username, password, and contactPoint.

   username = "<username>"
   password = "<password>"
   contactPoint = "<contact-point>"
   

5. Configure the SSLContext by creating a new variable named ssl_context, setting the protocol to PROTOCOL_TLS_CLIENT, disabling the hostname check, and setting the verification mode to CERT_NONE.

   ssl_context = SSLContext(PROTOCOL_TLS_CLIENT)
   ssl_context.check_hostname = False
   ssl_context.verify_mode = CERT_NONE
   

6. Create a new PlainTextAuthProvider object with the credentials specified in the previous steps. Store the result in a variable named auth_provider.

   auth_provider = PlainTextAuthProvider(username=username, password=password)
   

7. Create a Cluster object using the credential and configuration variables created in the previous steps. Store the result in a variable named cluster.

   cluster = Cluster([contactPoint], port=10350, auth_provider=auth_provider, ssl_context=ssl_context)
   

8. Connect to the cluster.

   session = cluster.connect("cosmicworks")
   

Next, upsert new data into a table. Upserting ensures that the data is created or replaced appropriately depending on whether the same data already exists in the table.

1. Create a new string variable named insertQuery with the Cassandra Query Language (CQL) query for inserting a new row.

   insertQuery = """
   INSERT INTO
       product (id, name, category, quantity, price, clearance)
   VALUES
       (%(id)s, %(name)s, %(category)s, %(quantity)s, %(price)s, %(clearance)s)
   """
   

2. Create a new object with various properties of a new product and store it in a variable named params.

   params = {
       "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
       "name": "Yamba Surfboard",
       "category": "gear-surf-surfboards",
       "quantity": 12,
       "price": 850.00,
       "clearance": False
   }
   

3. Use the execute function to run the query with the specified parameters.

   session.execute(insertQuery, params)
   

Then, read data that was previously upserted into the table.

1. Create a new string variable named readQuery with a CQL query that matches items with the same id field.

   readQuery = "SELECT * FROM product WHERE id = %s LIMIT 1"
   

2. Create a string variable named id with the same value as the product created earlier in this guide.

   id = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
   

3. Use the execute function to run the query stored in readQuery passing in the id variable as an argument. Store the result in a variable named readResults.

   readResults = session.execute(readQuery, (id,))
   

4. Use the one function get the expected single result. Store this single result in a variable named matchedProduct.

   matchedProduct = readResults.one()
   

Finally, use a query to find all data that matches a specific filter in the table.

1. Create string variables named findQuery and category with the CQL query and required parameter.

   findQuery = "SELECT * FROM product WHERE category = %s ALLOW FILTERING"
   category = "gear-surf-surfboards"
   

2. Use the two string variables and the execute function to query multiple results. Store the result of this query in a variable named findResults.

   findResults = session.execute(findQuery, (category,))
   

3. Use a for loop to iterate over the query results.

   for row in findResults:
       # Do something here with each result
   

Run the newly created application using a terminal in your application directory.

python app.py

When you no longer need the account, remove the account from your Azure subscription by deleting the resource.

az cosmosdb delete \
    --resource-group "<resource-group-name>" \
    --name "<account-name>"