The list_vector_buckets interface lists vector buckets. This article explains how to list vector buckets using the list_vector_buckets interface of TOS Vectors Python SDK.

Notes

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

To prevent key leakage, this article's sample code reads the Access Key ID and Secret Access Key from environment variables. Therefore, before using the SDK, you must configure long-term access credentials. For details, see configure long-term access credentials.

TOS Vectors Python SDK supports temporary access credentials and allows configuring timeout and retry policies. You can adjust these settings flexibly based on your business needs to enhance application security. For details, see common configuration scenarios.

Permissions required

The main account has full permissions by default, but IAM users have no permissions by default. If you want to use a sub-account to perform the list_vector_buckets operation, the main account must grant the following permissions to the sub-account via IAM policies and bucket policies:

tosvectors:ListVectorBuckets

Code example

List vector buckets with pagination

# Paged enumeration vector storage bucket​
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'​
​
try:​
    # Create a VectorClient object; all vector operations are handled through VectorClient​
    client = tos.VectorClient(ak, sk, endpoint, region)​
    ​
    # Page 1: Limit the number of returns to 2 buckets.​
    page1 = client.list_vector_buckets(max_results=2)​
    ​
    print("=== Results on page 1 ===")​
    print(f"Request ID: {page1.request_id}")​
    print(f"Status Code: {page1.status_code}")​
    print(f"Max Results: 2")​
    ​
    if page1.vector_buckets:​
        print(f"Found {len(page1.vector_buckets)} vector buckets in first page:")​
        for i, bucket in enumerate(page1.vector_buckets):​
            print(f"  {i+1}. Bucket Name: {bucket.vector_bucket_name}")​
            print(f"     Bucket TRN: {bucket.vector_bucket_trn}")​
    else:​
        print("No vector buckets found in first page.")​
    ​
    # If there is a next page, continue to get the second page.​
    if page1.next_token:​
        print(f"\nNext Token: {page1.next_token}")​
        print("\n=== Results on page 2 ===")​
        ​
        # Use next_token to get the next page of results.​
        page2 = client.list_vector_buckets(max_results=2, next_token=page1.next_token)​
        ​
        print(f"Request ID: {page2.request_id}")​
        print(f"Status Code: {page2.status_code}")​
        ​
        if page2.vector_buckets:​
            print(f"Found {len(page2.vector_buckets)} vector buckets in second page:")​
            for i, bucket in enumerate(page2.vector_buckets):​
                print(f"  {i+1}. Bucket Name: {bucket.vector_bucket_name}")​
                print(f"     Bucket TRN: {bucket.vector_bucket_trn}")​
        else:​
            print("No vector buckets found in second page.")​
            ​
        if page2.next_token:​
            print(f"\nNext Token: {page2.next_token}")​
    else:​
        print("\n All results are displayed on one page.")​
        ​
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))​

List vector buckets with prefix filtering

# Prefix-filtered enumeration vector bucket​
import os​
import tos​
import time​
​
# 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'​
​
try:​
    # Create a VectorClient object; all vector operations are handled through VectorClient​
    client = tos.VectorClient(ak, sk, endpoint, region)​
    ​
    # Set prefix filtering conditions - This uses a demo prefix; you can modify it as needed in actual use.​
    # Prefix filtering can help you filter out buckets with specific naming rules.​
    prefix_filter = "test-"​
    ​
    print(f"Use prefix filtering: '{prefix_filter}'")​
    ​
    # Call the list_vector_buckets method and filter using the prefix parameter.​
    result = client.list_vector_buckets(prefix=prefix_filter)​
    ​
    # Print the basic request information​
    print(f"\nRequest ID: {result.request_id}")​
    print(f"Status Code: {result.status_code}")​
    ​
    # Process the returned results​
    if result.vector_buckets:​
        print(f"\n Find {len(result.vector_buckets)} vector buckets that match the prefix:")​
        for i, bucket in enumerate(result.vector_buckets):​
            print(f"  {i+1}. Bucket Name: {bucket.vector_bucket_name}")​
            print(f"     Bucket TRN: {bucket.vector_bucket_trn}")​
            print(f"     Creation Time: {bucket.creation_time}")​
            ​
            # Verify that the bucket name does indeed begin with the specified prefix.​
            if bucket.vector_bucket_name.startswith(prefix_filter):​
                print(f"     ✓ Name verification passed: Starting with '{prefix_filter}'")​
            else:​
                print(f"     ✗ Name verification failed: Not starting with '{prefix_filter}'")​
    else:​
        print(f"\n No vector buckets with the prefix '{prefix_filter}' found")​
        print("You can：")​
        print("1. Check if a bucket with a matching prefix exists")​
        print("2. Try other prefix conditions")​
        print("3. First, create some storage buckets with this prefix for testing")​
        ​
    # Check if there is a next page (even with prefix filtering, the results may still be paginated).​
    if result.next_token:​
        print(f"\nNext Token: {result.next_token}")​
        print("More results are available; you can use `next_token` to get the next page.")​
        ​
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))​