List Vectors

Use the list vectors operation to retrieve vectors from a table by their IDs.

The operation lists vector records with their IDs, embeddings, and metadata. Pagination is supported for large result sets.

See the following for examples of how to implement list_vectors:

from oracle_vecdb import OracleVecDB, Configuration

client = OracleVecDB(Configuration(
    rest_url="https://<host>/ords/<schema>/_/db-api/stable/vecdb/",
    access_token="<bearer-token>", # or username="<user>", password="<pass>"
))

#get specific vectors by ID
vectors = client.list_vectors(
    table_name='products',
    ids=['prod_1', 'prod_2', 'prod_3']
)
print(vectors)

#paginate through results, including only the first 10 results
page1 = client.list_vectors(
    table_name='products',
    limit=10,
    offset=0
)
print(page1)

#then, paginate through the next 10 results
page2 = client.list_vectors(
    table_name='products',
    limit=10,
    offset=10
)
print(page2)

A JSON response is returned containing matching vectors with the following information:

IDs
Dense vectors
Metadata

Example response:

{
    "items": [
        {
            "id": "prod_010",
            "dense_vector": [0.21, 0.19, 0.24, 0.47, 0.40],
            "metadata": {
                "name": "Halo Headphones",
                "category": "electronics",
                "price": 199.0,
                "color": "onyx"
            }
        },
        {
            "id": "prod_003",
            "dense_vector": [0.08, 0.25, 0.34, 0.41, 0.50],
            "metadata": {
                "name": "Zephyr Running Tee",
                "category": "apparel",
                "price": 39.95,
                "color": "light grey"
            }
        }
    ],
    "limit": 15,
    "offset": 0,
    "count": 10
}

See how POST /vecdb/vector-tables/{vector_table_name}/list can be used in the following examples:

Get specific vectors by ID:

curl -X POST \
  "https://<host>:<port>/ords/<schema>/_/db-api/stable/vecdb/vector-tables/sample_table/list" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  # Choose ONE authentication method:

  # Option 1: Basic authentication
  -u "<user>:<password>" \

  # Option 2: OAuth Bearer token
  # -H "Authorization: Bearer <access_token>" \

  -d '{
    "ids": ["id1", "id2"],
    "limit": 2,
    "offset": 0
  }'

Paginate through results (first 10 results):

curl -X POST \
  "https://<host>:<port>/ords/<schema>/_/db-api/stable/vecdb/vector-tables/sample_table/list" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -u "<user>:<password>" \
  -d '{
    "limit": 10,
    "offset": 0
  }'

Paginate through the next 10 results:

curl -X POST \
  "https://<host>:<port>/ords/<schema>/_/db-api/stable/vecdb/vector-tables/sample_table/list" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -u "<user>:<password>" \
  -d '{
    "limit": 10,
    "offset": 10
  }'

Responses:

Example 200 response:

{
  "items": [
    {
      "id": "id1",
      "dense_vector": [0.1, 0.5, 0.4, 0.56],
      "metadata": {
        "product_name": "Noise Cancelling Headphones",
        "category": "electronics",
        "brand": "Sony",
        "price": 299.99
      }
    },
    {
      "id": "id2",
      "dense_vector": [0.14, 0.534, 0.12, 0.58],
      "metadata": {
        "product_name": "Studio Monitor Headphones",
        "category": "electronics",
        "brand": "Audio-Technica",
        "price": 149.99
      }
    }
  ],
  "limit": 2,
  "offset": 0,
  "count": 2
}

400 - the request body included invalid parameters.
404 - the specified vector table does not exist.

See how DBMS_VECTOR_DATABASE.LIST_VECTORS can be used in the following example:

dbms_vector_database.list_vectors(
    table_name => 'sample_table',
    ids => JSON('["id1", "id2"]')
);

Example response:

{
  "items": [
    {
      "id": "id1",
      "dense_vector": [0.1, 0.5, 0.4, 0.56],
      "metadata": {
        "product_name": "Noise Cancelling Headphones",
        "category": "electronics",
        "brand": "Sony",
        "price": 299.99
      }
    },
    {
      "id": "id2",
      "dense_vector": [0.14, 0.534, 0.12, 0.58],
      "metadata": {
        "product_name": "Studio Monitor Headphones",
        "category": "electronics",
        "brand": "Audio-Technica",
        "price": 149.99
      }
    }
  ],
  "limit": 2,
  "offset": 0,
  "count": 2
}

For more information about the PL/SQL implementation, including parameters, see LIST_VECTORS.