The list_vectors interface lists vector data in a specified collection. This article explains how to use the list_vectors interface of the TOS Vectors Python SDK to get a list of vectors.

Notes

You need to fill in the region and access domain in the sample code according to your actual situation. For details, see Region and Access Domain (Endpoint).

To prevent key leaks, the sample code reads the Access Key ID and Secret Access Key from environment variables. Before using the SDK, you need to configure long-term access credentials. For details, see Configure Long-Term Access Credentials.

The TOS Vectors Python SDK supports temporary access credentials; it also supports timeout settings, retry policies, and other mechanisms. You can configure these flexibly according to your business needs to improve application security. For details, see Common Configuration Scenarios.

TOS Vectors supports vector float32 precision at the core. Passing vectors with higher precision may cause precision loss.

Permissions required

The main account has all permissions by default, but IAM users have no permissions by default. If you need to perform the list_vectors operation using a sub-account, the main account must grant the following permissions to the sub-account through IAM policy and bucket policy:

tosvectors:ListVectors

Code example

Basic usage of listing vectors

# List the basic usage of vectors.​
import os​
import tos​
​
# Retrieve AK and SK information from environment variables.​
ak = os.getenv('TOS_ACCESS_KEY')​
sk = os.getenv('TOS_SECRET_KEY')​
# Fill in your endpoint and your region with the endpoint corresponding to the bucket's region. # For example, for China (Beijing), set your endpoint to https://tosvectors-cn-beijing.volces.com and your region to cn-beijing.​
endpoint = 'Provide your endpoint'​
region = 'Provide your region'​
vector_bucket_name = 'Provide your bucket name'​
account_id = os.getenv('TOS_ACCOUNT_ID')​
​
try:​
    # Create a VectorClient object; all vector operations are handled through VectorClient.​
    client = tos.VectorClient(ak, sk, endpoint, region)​
    ​
    # Set the vector index name and account ID​
    index_name = "test"​
​
    ​
    # List vectors and return data and metadata.​
    print("\n=== List vectors (return data and metadata) ===")​
    result_with_data = client.list_vectors(​
        vector_bucket_name=vector_bucket_name,​
        index_name=index_name,​
        account_id=account_id,​
        return_data=True,      # Return vector data​
        return_metadata=True     # Return vector metadata​
    )​
    ​
    print(f"Request ID: {result_with_data.request_id}")​
    print(f"Number of returned vectors: {len(result_with_data.vectors)}")​
    ​
    # Print detailed vector information​
    if result_with_data.vectors:​
        vector = result_with_data.vectors[0]​
        print(f"Details of the first vector:")​
        print(f"  Key: {vector.key}")​
        if vector.data and vector.data.float32:​
            print(f"  Data length: {len(vector.data.float32)}")​
            print(f"  Data value: {vector.data.float32}")​
        if vector.metadata:​
            print(f"  Metadata: {vector.metadata}")​
    ​
    # 限制返回数量​
    print("\n=== Limit the number of returns ===")​
    result_limited = client.list_vectors(​
        vector_bucket_name=vector_bucket_name,​
        index_name=index_name,​
        account_id=account_id,​
        max_results=3  # Return up to 3 vectors​
    )​
    ​
    print(f"Request ID: {result_limited.request_id}")​
    print(f"Number of returned vectors: {len(result_limited.vectors)}")​
    ​
except tos.exceptions.TosClientError as e:​
    # The operation failed and a client exception was caught. This is usually due to invalid request parameters or a network exception.​
    print('fail with client error, message:{}, cause: {}'.format(e.message, e.cause))​
except tos.exceptions.TosServerError as e:​
    # The operation failed and a server exception occurred. See the response for the error details.​
    print('fail with server error, code: {}'.format(e.code))​
    # Use the request ID for troubleshooting purposes. We strongly recommend including the request ID in the logs.​
    print('error with request id: {}'.format(e.request_id))​
    print('error with message: {}'.format(e.message))​
    print('error with http code: {}'.format(e.status_code))​
    print('error with ec: {}'.format(e.ec))​
    print('error with request url: {}'.format(e.request_url))​
except Exception as e:​
    print('fail with unknown error: {}'.format(e))​

Paginated listing of vectors

# Paginated listing of vectors​
import os​
import tos​
​
# Retrieve AK and SK information from environment variables.​
ak = os.getenv("TOS_ACCESS_KEY")​
sk = os.getenv("TOS_SECRET_KEY")​
# Fill in your endpoint and your region with the endpoint corresponding to the bucket's region. # For example, for China (Beijing), set your endpoint to https://tosvectors-cn-beijing.volces.com and your region to cn-beijing.​
endpoint = os.getenv("TOS_ENDPOINT")​
region = os.getenv("TOS_REGION")​
vector_bucket_name = os.getenv("TOS_BUCKET")​
​
try:​
    # Create a VectorClient object; all vector operations are handled through VectorClient.​
    client = tos.VectorClient(ak, sk, endpoint, region)​
​
    # Set vector index name and account ID.​
    index_name = "test"​
    account_id = os.getenv("TOS_ACCOUNT_ID")​
​
    # Pagination parameter settings​
    page_size = 5  # Return 5 vectors per page​
    all_vectors = []  # Store all the obtained vectors​
    page_count = 0  # Page Counter​
​
    print("=== Start paginated listing of vectors ===")​
​
    # First page request​
    page_count += 1​
    print(f"\n--- Page {page_count} ---")​
    result = client.list_vectors(​
        vector_bucket_name=vector_bucket_name,​
        index_name=index_name,​
        account_id=account_id,​
        max_results=page_size,  # Number of items returned per page​
        return_data=True,  # Return vector data​
        return_metadata=True,  # Return vector metadata​
    )​
​
    print(f"Request ID: {result.request_id}")​
    print(f"Status code: {result.status_code}")​
    print(f"Number of return vectors on this page: {len(result.vectors)}")​
​
    # Save the vector of the first page​
    all_vectors.extend(result.vectors)​
​
    # Print the basic information of the first page vector​
    for i, vector in enumerate(result.vectors):​
        print(f"Vector {i+1}: Key={vector.key}")​
        if vector.data and vector.data.float32:​
            print(f"  Data dimension: {len(vector.data.float32)}")​
        if vector.metadata:​
            print(f"  Metadata: {vector.metadata}")​
​
    # Check if there is a next page.​
    next_token = result.next_token​
​
    # If there is a next page token, continue to retrieve subsequent pages.​
    while next_token and len(result.vectors) > 0:​
        page_count += 1​
        print(f"\n--- Page {page_count} ---")​
​
        result = client.list_vectors(​
            vector_bucket_name=vector_bucket_name,​
            index_name=index_name,​
            account_id=account_id,​
            max_results=page_size,​
            next_token=next_token,  # Use the token returned from the previous page​
            return_data=True,​
            return_metadata=True,​
        )​
​
        print(f"Request ID: {result.request_id}")​
        print(f"Number of return vectors on this page: {len(result.vectors)}")​
​
        # Save the vector of the current page.​
        all_vectors.extend(result.vectors)​
​
        # Print the basic information of the current page vector.​
        for i, vector in enumerate(result.vectors):​
            print(f"Vector {i+1}: Key={vector.key}")​
​
        # Update next_token, and stop if it is None or returns an empty result.​
        next_token = result.next_token​
​
        # If the number of returned vectors is less than page_size, it indicates the last page.​
        if len(result.vectors) < page_size:​
            print("You have reached the last page")​
            break​
​
    # Summary results.​
    print(f"\n=== Pagination listing completed ===")​
    print(f"Total pages: {page_count}")​
    print(f"Total number of vectors: {len(all_vectors)}")​
​
    # Verify the uniqueness of the vector key.​
    vector_keys = [v.key for v in all_vectors]​
    unique_keys = set(vector_keys)​
    print(f"Number of unique vector keys: {len(unique_keys)}")​
​
    # Show detailed information of partial vectors.​
    if all_vectors:​
        print(f"\n Detailed information of the vector:")​
        for i in range(len(all_vectors)):​
            vector = all_vectors[i]​
            print(f"Vector {i+1}:")​
            print(f"  Key: {vector.key}")​
            if vector.data and vector.data.float32:​
                print(f"  Data length: {len(vector.data.float32)}")​
                print(f"  Data value: {vector.data.float32}")​
            if vector.metadata:​
                print(f"  Metadata: {vector.metadata}")​
​
except tos.exceptions.TosClientError as e:​
    # The operation failed and a client exception was caught. This is usually due to invalid request parameters or a network exception.​
    print("fail with client error, message:{}, cause: {}".format(e.message, e.cause))​
except tos.exceptions.TosServerError as e:​
    # The operation failed and a server exception occurred. See the response for the error details.​
    print("fail with server error, code: {}".format(e.code))​
    # Use the request ID for troubleshooting purposes. We strongly recommend including the request ID in the logs.​
    print("error with request id: {}".format(e.request_id))​
    print("error with message: {}".format(e.message))​
    print("error with http code: {}".format(e.status_code))​
    print("error with ec: {}".format(e.ec))​
    print("error with request url: {}".format(e.request_url))​
except Exception as e:​
    print("fail with unknown error: {}".format(e))​
​