All Products
Search

This Product

    AnalyticDB:Quick Start for Vector Engine

    Document Center

    AnalyticDB:Quick Start for Vector Engine

    Last Updated:Mar 30, 2026

    AnalyticDB for PostgreSQL's Vector Engine Optimization lets you store, index, and query high-dimensional vectors alongside structured data — all within a single PostgreSQL-compatible instance. This guide walks you through the full workflow:

    1. Create an instance with Vector Engine Optimization enabled.

    2. Set up an account and configure access.

    3. Connect to the database using psql.

    4. Import vector data and build indexes.

    5. Run vector search and hybrid search queries.

    Billing

    Creating an instance incurs charges for compute and storage resources. For pricing details, see Pricing.

    Free trial

    New users can apply for a free trial on Storage-elastic Mode instances at Alibaba Cloud Free Trial. If you are not eligible, follow the steps below to create a pay-as-you-go instance.

    Prerequisites

    Before you begin, ensure that you have:

    • An Alibaba Cloud account. Register one at alibabacloud.com if needed.

    • Authorized the service-linked role for AnalyticDB for PostgreSQL. The first time you open the console, click Create Instance in the upper-right corner — a Create Service Linked Role dialog box appears. Click OK to authorize.

    Step 1: Create an instance

    1. Log on to the AnalyticDB for PostgreSQL console.

    2. In the upper-right corner, click Create Instance.

    3. On the instance purchase page, configure the parameters below. You can keep the defaults for all other parameters. For the full parameter reference, see Create an instance.

      Parameter Description Example value
      Product type Subscription: Prepaid, suitable for long-term use with volume discounts. Pay-as-you-go: Billed hourly, suitable for short-term or trial use. Pay-as-you-go
      Region and zone The geographic location of the instance. This cannot be changed after creation. To use the internal network, select the same region as your ECS instances. China (Hangzhou): Zone J
      Instance resource type Elastic Storage Mode: Supports independent disk scale-out and smooth online scale-out. Serverless Pro: Specify only the computing resources you need — no storage reservation required. Elastic Storage Mode
      Database engine version Select 7.0 Standard Edition for the richest feature set. 6.0 Standard Edition is also supported. 7.0 Standard Edition
      Instance edition High-performance (Basic Edition): Suitable for most analytical workloads. High-availability Edition: Recommended for production and core business services. High-performance (Basic Edition)
      Vector Engine Optimization Select Enable to activate vector search capabilities. Enable
      Virtual Private Cloud Select the VPC for the instance. To connect over the internal network, select the same VPC as your ECS instances. Create a VPC and vSwitch if none are available. vpc-xxxx
      vSwitch Select a vSwitch within the VPC. If none are available in the current zone, switch zones or create a vSwitch. vsw-xxxx

    4. Click Buy Now, confirm the order, and click Activate Now.

    5. After payment, click Management Console to return to the instance list.

    Instance initialization takes a few minutes. Wait until the instance status changes to Running before proceeding.

    Step 2: Create an initial account

    Important

    AnalyticDB for PostgreSQL has two account types:

    • Privileged user: The initial account, granted the RDS_SUPERUSER role with full operational permissions on the database.

    • Regular user: No permissions by default. A privileged user (or a user with GRANT permission) must explicitly grant access. See Create and manage users.

    1. In the left navigation pane of the instance details page, click Account Management.

    2. Click Create Account and configure the following:

      Important

      Change your password regularly and avoid reusing old passwords.

      Parameter Requirements
      Account Lowercase letters, digits, and underscores (_) only. Must start with a lowercase letter and end with a lowercase letter or digit. Cannot start with gp. Length: 2–16 characters.
      New Password and Confirm Password Must include at least three of the following: uppercase letters, lowercase letters, digits, and special characters (! @ # $ % ^ & * ( ) _ + - =). Length: 8–32 characters.

    3. Click OK.

    Step 3: Configure a whitelist

    If you connect to the instance exclusively through Data Management (DMS), skip this step. If you connect from a local IDE or an ECS instance, add the client's IP address to the whitelist. To find your client IP address, see Configure an IP address whitelist.

    1. In the left navigation pane, click Security Controls.

    2. Click Create Whitelist and configure the following:

      Warning

      Setting the prefix length to 0 (e.g., 0.0.0.0/0) allows all IP addresses to access the instance — this is a high security risk. The address 127.0.0.1 blocks all external access.

      Parameter Requirements
      Whitelist name Lowercase letters, digits, and underscores (_) only. Must start with a lowercase letter and end with a lowercase letter or digit. Length: 2–32 characters.
      IP addresses Separate multiple addresses with commas (,). Up to 999 unique addresses. Accepts specific IPs (e.g., 10.23.12.24) and CIDR blocks (e.g., 10.23.12.24/24, prefix length 1–32).

    3. Click OK.

    Step 4: Connect to the database

    The following example uses psql. For other connection methods, see Client connection.

    1. Install psql.

      1. Download the psql package. The following command applies to RHEL 7 and CentOS 7. For other OS versions, see Client connection.

        wget https://docs-aliyun.cn-hangzhou.oss.aliyun-inc.com/assets/attach/181125/cn_zh/1598426198114/adbpg_client_package.el7.x86_64.tar.gz

      2. Extract the package.

        tar -xzvf adbpg_client_package.el7.x86_64.tar.gz

      3. Go to the psql binary directory.

        cd adbpg_client_package/bin

    2. Connect to the database.

      ./psql -h <endpoint> -p 5432 -d <database> -U <account>

      Replace the placeholders as follows:

      Placeholder Description Where to find it
      <endpoint> Internal or public endpoint Console → instance details → Basic Information → Database Connection Information → Internal Endpoint. For public endpoint setup, see Manage public endpoints.
      <database> Database to connect to postgres (default)
      <account> Account name The account created in Step 2

      Example:

      psql -h gp-bp13zq652yy4p****-master.gpdb.rds.aliyuncs.com -p 5432 -d postgres -U testuser

      Enter the password when prompted. A successful connection displays the postgres=> prompt.

      Use the internal endpoint if the client runs on an ECS instance in the same region and VPC. Use the public endpoint for connections from outside Alibaba Cloud or from a different region.

    Step 5: Import vector data

    Verify the FastANN extension

    Run the following command to check whether the FastANN vector search extension is installed:

    \dx fastann

    If extension details are returned, the extension is ready. If nothing is returned, submit a ticket to request installation.

    Download sample data

    AnalyticDB for PostgreSQL provides sample car data for this tutorial. Download it with:

    wget https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20230606/uzkx/vector_sample_data.csv

    The sample table has the following schema:

    Field Type Description
    id bigint Record ID
    market_time timestamp Time when the car was launched
    color varchar(10) Car color
    price int Car price
    feature float4[] Feature vector of the car photo

    Set up the database and table

    Connect to psql and run the following SQL statements:

    -- Create and switch to a new database
CREATE DATABASE testdb;
\c testdb

-- Create a schema and table with a vector field
-- When Vector Engine Optimization is enabled, the default storage engine is heap
CREATE SCHEMA IF NOT EXISTS vector_test;
CREATE TABLE IF NOT EXISTS vector_test.car_info (
  id         bigint       NOT NULL,
  market_time timestamp,
  color      varchar(10),
  price      int,
  feature    float4[],
  PRIMARY KEY(id)
)
USING heap
DISTRIBUTED BY(id);

    Create indexes

    Create structured indexes on the scalar fields and a vector index on the feature vector:

    -- Change the storage format of the vector field to PLAIN.
ALTER TABLE vector_test.car_info ALTER COLUMN feature SET STORAGE PLAIN;

-- Structured indexes on scalar fields
CREATE INDEX ON vector_test.car_info(market_time);
CREATE INDEX ON vector_test.car_info(color);
CREATE INDEX ON vector_test.car_info(price);

-- Vector index using the FastANN ANN algorithm (10 dimensions, PQ disabled)
CREATE INDEX ON vector_test.car_info USING ann(feature) WITH (dim='10', pq_enable='0');

    Load the data

    \COPY vector_test.car_info FROM '/path/to/vector_sample_data.csv';

    Replace /path/to/vector_sample_data.csv with the actual file path. For example, if you downloaded the file to /home, use /home/vector_sample_data.csv.

    A successful import returns:

    COPY 10000

    Step 6: Run vector search queries

    All three examples below use the <-> operator to order results by vector distance, then apply a distance function to compute the metric value.

    Euclidean distance

    l2_squared_distance() returns the squared L2 (Euclidean) distance between two vectors. Lower values indicate closer matches.

    SELECT id,
       l2_squared_distance(feature,
         array[0.495181661387,0.108697291209,0.181728549067,0.109680543346,
               0.19713082404,0.0197809514512,0.534227452778,0.442411970815,
               0.409909873031,0.0975687394505]::float4[]) AS distance
FROM vector_test.car_info
ORDER BY feature <-> array[0.495181661387,0.108697291209,0.181728549067,0.109680543346,
                            0.19713082404,0.0197809514512,0.534227452778,0.442411970815,
                            0.409909873031,0.0975687394505]::float4[]
LIMIT 10;

    Sample output:

      id  |      distance
------+--------------------
    2 |                  0
 1331 | 0.0677967891097069
 1543 |  0.079616591334343
 5606 | 0.0892329216003418
 6423 | 0.0894578248262405
 1667 | 0.0903968289494514
 8215 | 0.0936210229992867
 7801 | 0.0952572822570801
 2581 | 0.0965127795934677
 2645 | 0.0987173467874527
(10 rows)

    Dot product distance (cosine similarity)

    dp_distance() returns the dot product distance. When vectors are normalized, dot product distance equals cosine similarity — higher values indicate closer matches.

    SELECT id,
       dp_distance(feature,
         array[0.495181661387,0.108697291209,0.181728549067,0.109680543346,
               0.19713082404,0.0197809514512,0.534227452778,0.442411970815,
               0.409909873031,0.0975687394505]::float4[]) AS similarity
FROM vector_test.car_info
ORDER BY feature <-> array[0.495181661387,0.108697291209,0.181728549067,0.109680543346,
                            0.19713082404,0.0197809514512,0.534227452778,0.442411970815,
                            0.409909873031,0.0975687394505]::float4[]
LIMIT 10;

    Sample output:

      id  |    similarity
------+-------------------
    2 |                 1
 1331 | 0.966101586818695
 1543 | 0.960191607475281
 5606 | 0.955383539199829
 6423 | 0.955271065235138
 1667 | 0.954801559448242
 8215 | 0.953189492225647
 7801 |  0.95237135887146
 2581 | 0.951743602752686
 2645 | 0.950641334056854
(10 rows)

    Hybrid search

    Filter on structured fields while ranking results by vector similarity. The query below retrieves cars launched between October 30, 2020 and January 1, 2021, colored red, white, or blue, priced under 100, ranked by vector similarity:

    SELECT id,
       dp_distance(feature,
         array[0.495181661387,0.108697291209,0.181728549067,0.109680543346,
               0.19713082404,0.0197809514512,0.534227452778,0.442411970815,
               0.409909873031,0.0975687394505]::float4[]) AS similarity
FROM vector_test.car_info
WHERE market_time >= '2020-10-30 00:00:00'
  AND market_time < '2021-01-01 00:00:00'
  AND color IN ('red', 'white', 'blue')
  AND price < 100
ORDER BY feature <-> array[0.495181661387,0.108697291209,0.181728549067,0.109680543346,
                            0.19713082404,0.0197809514512,0.534227452778,0.442411970815,
                            0.409909873031,0.0975687394505]::float4[]
LIMIT 10;

    Sample output:

      id  |    similarity
------+-------------------
 7645 | 0.922723233699799
 8956 | 0.920517802238464
 8219 |  0.91210675239563
 8503 | 0.895939946174622
 5113 | 0.895431876182556
 7680 | 0.893448948860168
 8433 | 0.893425941467285
 3604 |  0.89293098449707
 3945 | 0.891274154186249
 7153 | 0.891128540039062
(10 rows)

    What's next