Package: astrapy
AstraPyAstraPy is a Pythonic SDK forDataStax AstraPart I - Getting Started1.1 Install AstraPy1.2 Setup your Astra clientPart II - Collections2.1 Create and delete vector collections2.2 Connect to existing collectionPart III - Inserting Documents3.1 - Inserting a document3.2 - Inserting multiple documents3.3 - Inserting multiple documents3.4 - Creating a subdocument3.5 - Create a document without an IDPart IV - Updating Documents4.1 - Update a Document4.2 - Replace a Non-vector-documentPart V - Finding Documents5.1 - Find documents using vector search5.2 - Find documents using vector search and projection5.3 - Find one and update with vector search5.4 Find one and replace with vector searchPart VI - Deleting Documents6.1 Delete a Subdocument6.2 Delete a DocumentPart I - Getting Started1.1 Install AstraPypipinstallastrapy1.2 Setup your Astra clientCreate a.envfile with the appropriate values:ASTRA_DB_APPLICATION_TOKEN="<AstraCS:...>"ASTRA_DB_API_ENDPOINT="<https://...>"If you haveAstra CLIinstalled, you can create the.envfile withastra db create-dotenv DATABASE_NAME.Load the variables in and then create the client. This collections client can make non-vector and vector calls, depending on the call configuration.importosfromdotenvimportload_dotenvfromastrapy.dbimportAstraDB,AstraDBCollectionfromastrapy.opsimportAstraDBOpsload_dotenv()# Grab the Astra token and api endpoint from the environmenttoken=os.getenv("ASTRA_DB_APPLICATION_TOKEN")api_endpoint=os.getenv("ASTRA_DB_API_ENDPOINT")# Initialize our vector dbastra_db=AstraDB(token=token,api_endpoint=api_endpoint)Part II - Collections2.1 Create and Delete Vector CollectionsCreate a vector collection with dimension of 5
If you were using OpenAI here you would use 1376 as the value# Create a collection and then delete itastra_db.create_collection(collection_name="collection_test_delete",dimension=5)astra_db.delete_collection(collection_name="collection_test_delete")# Double check the collections in your vector storeastra_db.get_collections()At this point you have a collection named "collection_test" to do the following operationsIn the next section, you will be creating the object for your collection2.2 Connect to existing collection# The return of create_collection() will return the collectioncollection=astra_db.create_collection(collection_name="collection_test",dimension=5)# Or you can connect to an existing connection directlycollection=AstraDBCollection(collection_name="collection_test",astra_db=astra_db)# You don't even need the astra_db objectcollection=AstraDBCollection(collection_name="collection_test",token=token,api_endpoint=api_endpoint)Part III - Inserting Documents3.1 Inserting a documentHere is an example of inserting a vector object into your vector store (collection), followed by running a find command to retrieve the document. The first find command fails because that object does not exist. The second find command should succeed.collection.insert_one({"_id":"5","name":"Coded Cleats Copy","description":"ChatGPT integrated sneakers that talk to you","$vector":[0.25,0.25,0.25,0.25,0.25],})collection.find_one({"name":"potato"})# Not foundcollection.find_one({"name":"Coded Cleats Copy"})3.2 Inserting multiple documentsHere is an example of inserting a number of documents into your collection. Note that the json object is 'documents' here, not 'document' as it is in insert_one.In the first insert, the default behavior is in place. If you are inserting documents that already exist, you will get an error and the process will end.These two examples are using non-vector objects.documents=[{"_id":"id_1","first_name":"Dang","last_name":"Son",},{"_id":"id_2","first_name":"Yep","last_name":"Boss",},]response=collection.insert_many(documents=documents)In the following insert_many example, options are set so that it skips errors and only inserts successful entries.documents2=[{"_id":"id_2","first_name":"Yep","last_name":"Boss",},{"_id":"id_3","first_name":"Miv","last_name":"Fuff",},]response=collection.insert_many(documents=documents2,partial_failures_allowed=True,)3.3 Inserting multiple vector documentsThe following code inserts vector objects into the collection in your vector store.json_query=[{"_id":str(uuid.uuid4()),"name":"Coded Cleats","description":"ChatGPT integrated sneakers that talk to you","$vector":[0.1,0.15,0.3,0.12,0.05],},{"_id":str(uuid.uuid4()),"name":"Logic Layers","description":"An AI quilt to help you sleep forever","$vector":[0.45,0.09,0.01,0.2,0.11],},{"_id":vv_uuid,"name":"Vision Vector Frame","description":"Vision Vector Frame - A deep learning display that controls your mood","$vector":[0.1,0.05,0.08,0.3,0.6],},]res=collection.insert_many(documents=json_query)3.4 Creating a subdocumentThe following code uses update to create or update a sub-document under one of your existing documents.document=collection.update_one(filter={"_id":"id_1"},update={"$set":{"name":"Eric"}},)document=collection.find_one(filter={"_id":"id_1"})3.5 Create a document without an IDresponse=collection.insert_one(document={"first_name":"New","last_name":"Guy",})document=collection.find_one(filter={"first_name":"New"})Part IV - Updating Documents4.1 Update a documentcollection.update_one(filter={"_id":cliff_uuid},update={"$set":{"name":"Bob"}},)document=collection.find_one(filter={"_id":"id_1"})4.2 Replace a non-vector documentcollection.find_one_and_replace(filter={"_id":"id_1"},replacement={"_id":"id_1","addresses":{"work":{"city":"New York","state":"NY",}},},)document=collection.find_one(filter={"_id":"id_1"})document_2=collection.find_one(filter={"_id":cliff_uuid},projection={"addresses.work.city":1})Part V - Finding DocumentsThe below examples show our high-level interfaces for finding documents. Note that corresponding low-level functionality exists, i.e., the high-level interfacevector_findis a wrapper around thefindfunction, as available in the JSON API.5.1 Find documents using vector searchdocuments=collection.vector_find([0.15,0.1,0.1,0.35,0.55],limit=100,)5.2 Find documents using vector search and projectiondocuments=collection.vector_find([0.15,0.1,0.1,0.35,0.55],limit=100,fields=["$vector"],)5.3 Find one and update with vector searchupdate={"$set":{"status":"active"}}document=collection.find_one(filter={"status":"active"})collection.vector_find_one_and_update([0.15,0.1,0.1,0.35,0.55],update=update,)document=collection.find_one(filter={"status":"active"})5.4 Find one and replace with vector searchreplacement={"_id":"1","name":"Vision Vector Frame","description":"Vision Vector Frame - A deep learning display that controls your mood","$vector":[0.1,0.05,0.08,0.3,0.6],"status":"inactive",}collection.vector_find_one_and_replace([0.15,0.1,0.1,0.35,0.55],replacement=replacement,)document=collection.find_one(filter={"name":"Vision Vector Frame"})Part VI - Deleting Documents6.1 Delete a subdocumentresponse=collection.delete_subdocument(id="id_1",subdoc="addresses")document=collection.find(filter={"_id":"id_1"})6.2 Delete a documentresponse=collection.delete(id="id_1")More InformationCheck out thenotebookwhich has examples for finding and inserting information into the database, including vector commands.Take a look at theAstra DB DML testsfor specific endpoint examples. Further examples are available in the other correspondingtest files.Using the Ops ClientYou can use the Ops client to work with the Astra DevOps API. Check thedevops testsFor DevelopersInstall poetrypipinstallpoetryInstall the project dependenciespoetryinstallStyle, linter, typingAstraPy tries to be consistent in code style and linting.
Moreover,type annotationsare used everywhere.To ensure the code complies, you should get no errors
(Success: no issues found...) when running the following in the root dir:poetryrunblack--checkastrapy&&poetryrunruffastrapy&&poetryrunmypyastrapyLikewise, for the tests:poetryrunblack--checktests&&poetryrunrufftests&&poetryrunmypytestsTestingEnsure you provide all required environment variables (you can do so by editingtests/.envaftertests/.env.template):exportASTRA_DB_APPLICATION_TOKEN="..."exportASTRA_DB_API_ENDPOINT="..."exportASTRA_DB_KEYSPACE="..."# OptionalexportASTRA_DB_ID="..."# For the Ops testing onlyexportASTRA_DB_OPS_APPLICATION_TOKEN="..."# Ops-only, falls back to the other tokenthen you can run:poetryrunpytestTo remove the noise from the logs (on by default), runpytest -o log_cli=0.To skip all collection deletions (done by default):TEST_SKIP_COLLECTION_DELETE=1poetryrunpytest[...]To enable theAstraDBOpstesting (off by default):TEST_ASTRADBOPS=1poetryrunpytest[...]