Get Started Using Autonomous AI Vector Database
The following sections act as a quick start to begin using Oracle Autonomous AI Vector Database, including a simple provisioning workflow, the basic steps to load a model, and how to create a new vector table.
Sign up for Oracle Cloud
On Oracle Cloud, sign up for Oracle Cloud Free Tier or sign up for a paid Cloud Account. You cannot create an Autonomous AI Vector Database instance until you do so.
See Welcome to Oracle Cloud Infrastructure for more information.
Quick Start Provisioning an Autonomous AI Vector Database
These steps demonstrate a quick and straightforward way to provision a new Autonomous AI Vector Database instance. For more detailed information about all of the available provisioning options, see Provision an Autonomous AI Vector Database Instance.
Perform the following prerequisite steps as necessary:
-
Open the Oracle Cloud Infrastructure Console by clicking the
next to Cloud. -
From the Oracle Cloud Infrastructure left navigation menu select Analytics & AI, and then select Autonomous AI Vector Database.
-
Choose your region. See Switching Regions for information on switching regions and working in multiple regions.
On the Autonomous AI Vector Database page, perform the following steps:
-
Select Create Autonomous AI Vector Database.
-
Provide basic information for the Autonomous AI Vector Database.
-
Display name Specify a user-friendly description or other information that helps you easily identify the resource. The display name does not have to be unique.
The default display name is a generated 16-character string that matches the default database name.
-
Database name Specify the database name; it must consist of letters and numbers only. The maximum length is 30 characters. The same database name cannot be used for multiple Autonomous AI Databases in the same tenancy in the same region.
The default database name is a generated 16-character string that matches the default display name.
-
Compartment. See Compartments for information on using and managing compartments.
-
-
Configure the database (ECPU billing model).
Note: For Autonomous AI Vector Databases, the Developer option is selected by default. If Developer is deselected, Always Free is selected automatically. These are the two available options for Vector Database. Note that if you already have the maximum two Autonomous AI Database instances running with Always Free, only the Developer option will be available.
-
Always Free: Select to show Always Free options.
You can only create a free instance in the tenancy’s Home region.
-
Developer: Select to show Autonomous AI Database for Developers options.
An Autonomous AI Database for Developers instance is a fixed shape database that is suited for development and testing use cases.
Selecting this option sets the Compute resources to a fixed value of 4 ECPUs and the Storage to 20 GB. If you require additional resources, a path to upgrade your instance to a full Autonomous AI Transaction Processing instance is available. For more information, see Upgrade an Autonomous AI Vector Database Instance for Production.
-
-
Create administrator credentials. Set and confirm the password for the Autonomous AI Database Admin user. The username is preset in a read only field.
The password must meet the strong password complexity criteria based on Oracle Cloud security standards. For more information on the password complexity rules, see About User Passwords on Autonomous Database.
-
Set the username and password for the Autonomous AI Vector Database user.
In addition to the admin credentials, a Vector Database user must also be created when provisioning an Autonomous AI Vector Database instance. This is the user that you will use to connect to the Vector Database.
-
Choose network access from one of the following options:
-
Secure access from everywhere
-
Secure access from allowed IPs and VCNs only
-
-
Select Create.
On the Oracle Cloud Infrastructure console the Lifecycle state shows Provisioning until the new database is available, which may take a few minutes.
Install the SDK
First ensure that Python is installed on your system. The versions supported with oracle-vecdb are Python 3.10 and later. You can check your version using the following command:
python --version
Note: On some platforms, the Python executable may be called python3 instead of python.
To install the Python SDK, use the following command:
python -m pip install oracle-vecdb --upgrade
Create a Client and Perform Simple Queries
Once you have installed the Python SDK, you can follow these example to first create a client and then create a table, upsert vectors, and perform a semantic search with filters. Note that you will need to input your own host and access_token (or username and password) values to create the client.
-
Configure the client:
from oracle_vecdb import OracleVecDB, Configuration config = Configuration( rest_url="https://<host>:<port>/ords/<schema>/_/db-api/stable/vecdb/", # choose one auth method access_token="<bearer-token>", # or username="<user>", password="<pass>", ) vecdb = OracleVecDB(config)Note: Proxies and retries can be configured using
Configuration. -
Create an integrated embedding table.
Create a table that generates embeddings from text stored in metadata. The configured model must already be available in Oracle AI Database.
vecdb.create_vector_table( name="demo", table_params={"auto_generate_id": True}, embed_params={ "model": "all_MiniLM_L12_v2", "embed_metadata_jsonpath": "content", }, ) -
Load model-backed records.
When integrated embedding is configured, provide text in the metadata field selected by
embed_metadata_jsonpath(in this case,"content"). The database generates the vector during upsert.vecdb.upsert_vectors( table_name="demo", vectors=[ { "metadata": { "title": "Comedy movie review", "content": "A lighthearted comedy with fast-paced jokes.", "genre": "comedy", } }, { "metadata": { "title": "Drama movie review", "content": "An emotional family drama with strong performances.", "genre": "drama", } }, ], ) -
Run a text query with filtering.
A text query uses the table’s configured embedding model to generate the query vector.
results = vecdb.query( table_name="demo", query_by={"text": "family drama"}, filters={"genre": {"$eq": "drama"}}, top_k=1, ) for index in range(len(results)): item = results[index] row = item if isinstance(item, dict) else item.model_dump() print(row["id"], row["distance"], row["metadata"])
Create a Table Bringing Your Own Vectors
For precomputed embeddings, omit the embed_params property from the vector table creation and provide dense_vector values in each record.
vecdb.create_vector_table(name="demo_byov")
vecdb.upsert_vectors(
table_name="demo_byov",
vectors=[
{"id": "1", "dense_vector": [0.1, 0.1], "metadata": {"genre": "comedy"}},
{"id": "2", "dense_vector": [0.2, 0.2], "metadata": {"genre": "drama"}},
],
)
results = vecdb.query(
table_name="demo_byov",
query_by={"vector": [0.15, 0.1]},
filters={"genre": {"$eq": "drama"}},
top_k=1,
)
for index in range(len(results)):
item = results[index]
row = item if isinstance(item, dict) else item.model_dump()
print(row["metadata"]["genre"])
Create Indexes and Perform Tuning
-
Delay index creation.
Create the table first and build its index explicitly when the data-loading workflow is complete.
vecdb.create_vector_table( name="demo_manual", index_params={"vector_index_params": {"auto_index": False}}, ) vecdb.create_index(table_name="demo_manual") -
Create an Hierarchical Navigable Small World (HNSW) index.
Use
INMEMORY GRAPHas the value fororganizationfor an HNSW-style vector index.vecdb.create_vector_table( name="demo_hnsw", index_params={ "vector_index_params": { "organization": "INMEMORY GRAPH", "advanced_params": { "neighbors": 32, "efConstruction": 200, }, }, }, ) -
Query-time HNSW tuning.
Tune HNSW search with
advanced_optionswithout rebuilding the index.results = vecdb.query( table_name="demo", query_by={"text": "family drama"}, filters={"genre": {"$eq": "drama"}}, top_k=1, advanced_options={ "idx_parameters": { "efsearch": 64, } }, )
For more in depth examples that demonstrate how to use Autonomous AI Vector Database, see the following resources on GitHub: