PolarDB:Quick start

Step 1: Create an intelligent search instance

1. Log on to the PolarDB-X (Distributed Edition) console.

2. Go to the Search engine instance list page.

3. In the upper-left corner of the page, select a region.

4. Click Create Instance. On the purchase or creation page, select the specification series, node specification, and node count, confirm the configuration, and submit.

5. After you submit the creation request, the instance state transitions from Creating to Running. Initialization typically completes within 5 to 10 minutes.

Step 2: Configure access credentials

1. In the instance list, click the Instance ID/Name to open the instance details page.

2. Switch to the Access Configuration tab and complete the following configuration:

   • Whitelist: Click Add Whitelist Group and add your business environment IP addresses to the whitelist.

   • Account Management: Click Create Account and create a username and password for REST API authentication.

     Note

     The password must be 8 to 32 characters in length and must include at least one uppercase letter, one lowercase letter, one digit, and one special character. The password must not contain consecutive characters (for example, 123 or abc) or common weak patterns.

   • Connection Information: Obtain the Internal Address or Public Endpoint and the corresponding port. To access the instance over the Internet, click Enable Now to enable the public endpoint.

For detailed steps, see Connection and access.

Step 3: Verify connectivity

After you add the client IP address to the whitelist, use curl to verify connectivity:

curl -XGET "http://<Search-engine-endpoint>:<port>" \
  -u "<username>:<password>"

Sample response:

{
  "name": "52901553",
  "cluster_name": "search-cluster-pxs-bjrf5gxxx",
  "cluster_uuid": "6pwOq28yS4Smtxxx",
  "version": {
    "distribution": "opensearch",
    "number": "3.6.0-SNAPSHOT",
    "build_type": "tar",
    "lucene_version": "10.4.0"
  },
  "tagline": "The OpenSearch Project: https://opensearch.org/"
}

Step 4: Create your first index

Create a search index that contains title and content fields:

curl -XPUT "http://<Search-engine-endpoint>:<port>/my-first-index" \
  -u "<username>:<password>" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "number_of_shards": 1,
      "number_of_replicas": 1
    },
    "mappings": {
      "properties": {
        "title":        { "type": "text", "analyzer": "ik_max_word" },
        "content":      { "type": "text", "analyzer": "ik_max_word" },
        "category":     { "type": "keyword" },
        "publish_date": { "type": "date" }
      }
    }
  }'

Step 5: Write test data

Use the _bulk API to batch-write several test documents:

curl -XPOST "http://<Search-engine-endpoint>:<port>/my-first-index/_bulk" \
  -u "<username>:<password>" \
  -H "Content-Type: application/json" \
  -d '
{"index": {"_id": "1"}}
{"title": "Introduction to PolarDB-X distributed database", "content": "PolarDB-X is a cloud-native distributed database that supports high-concurrency and high-availability online transaction processing.", "category": "Database", "publish_date": "2025-01-15"}
{"index": {"_id": "2"}}
{"title": "Getting started with OpenSearch full-text search", "content": "OpenSearch provides powerful full-text search capabilities and supports Chinese tokenization along with multiple query syntaxes.", "category": "Search", "publish_date": "2025-02-20"}
{"index": {"_id": "3"}}
{"title": "Vector search and AI applications", "content": "Vector search performs semantic similarity retrieval by calculating distances between vectors and is widely used in RAG and recommendation systems.", "category": "AI", "publish_date": "2025-03-10"}
'

Step 6: Run a full-text search

Search for documents that contain "distributed database":

curl -XPOST "http://<Search-engine-endpoint>:<port>/my-first-index/_search" \
  -u "<username>:<password>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "match": {
        "content": "distributed database"
      }
    },
    "highlight": {
      "fields": {
        "content": {}
      }
    }
  }'

Step 7: (Optional) Vector search example

• Create an index that supports vector search:

  curl -XPUT "http://<Search-engine-endpoint>:<port>/my-vector-index" \
    -u "<username>:<password>" \
    -H "Content-Type: application/json" \
    -d '{
      "settings": {
        "index.knn": true,
        "number_of_shards": 1,
        "number_of_replicas": 1
      },
      "mappings": {
        "properties": {
          "title":     { "type": "text" },
          "embedding": {
            "type": "knn_vector",
            "dimension": 4,
            "method": {
              "engine": "faiss",
              "name": "hnsw",
              "space_type": "l2"
            }
          }
        }
      }
    }'

• Write vector data and run a KNN query:

  curl -XPOST "http://<Search-engine-endpoint>:<port>/my-vector-index/_bulk" \
    -u "<username>:<password>" \
    -H "Content-Type: application/json" \
    -d '
  {"index": {"_id": "1"}}
  {"title": "Database technology", "embedding": [1.0, 2.0, 3.0, 4.0]}
  {"index": {"_id": "2"}}
  {"title": "Search engine", "embedding": [2.0, 3.0, 4.0, 5.0]}
  {"index": {"_id": "3"}}
  {"title": "Machine learning", "embedding": [5.0, 6.0, 7.0, 8.0]}
  '
  
  curl -XPOST "http://<Search-engine-endpoint>:<port>/my-vector-index/_search" \
    -u "<username>:<password>" \
    -H "Content-Type: application/json" \
    -d '{
      "size": 2,
      "query": {
        "knn": {
          "embedding": {
            "vector": [1.5, 2.5, 3.5, 4.5],
            "k": 2
          }
        }
      }
    }'

Clean up test data

If you no longer need the test indexes, delete them:

curl -XDELETE "http://<Search-engine-endpoint>:<port>/my-first-index" -u "<username>:<password>"
curl -XDELETE "http://<Search-engine-endpoint>:<port>/my-vector-index" -u "<username>:<password>"