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:

On the Autonomous AI Vector Database page, perform the following steps:

  1. Select Create Autonomous AI Vector Database.

  2. 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.

  3. 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.

  1. 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.

  2. 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.

  3. Choose network access from one of the following options:

    • Secure access from everywhere

    • Secure access from allowed IPs and VCNs only

  4. 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.

  1. 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.

  2. 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",
        },
    )
  3. 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",
          }
        },
      ],
    )
  4. 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

For more in depth examples that demonstrate how to use Autonomous AI Vector Database, see the following resources on GitHub: