All Products
Search
Document Center

AnalyticDB:QueryContent

Last Updated:Nov 05, 2025
This topic is generated by a machine translation engine without any human intervention. ALIBABA CLOUD DOES NOT GUARANTEE THE ACCURACY OF MACHINE TRANSLATED CONTENT. To request a human-translated version of this topic or provide feedback on this translation, please include it in the feedback form.

Retrieves vector data and metadata from a document collection by using natural statements.

Debugging

You can run this interface directly in OpenAPI Explorer, saving you the trouble of calculating signatures. After running successfully, OpenAPI Explorer can automatically generate SDK code samples.

Authorization information

The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:

  • Operation: the value that you can use in the Action element to specify the operation on a resource.
  • Access level: the access level of each operation. The levels are read, write, and list.
  • Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
    • For mandatory resource types, indicate with a prefix of * .
    • If the permissions cannot be granted at the resource level, All Resources is used in the Resource type column of the operation.
  • Condition Key: the condition key that is defined by the cloud service.
  • Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.
OperationAccess levelResource typeCondition keyAssociated operation
gpdb:QueryContentcreate
*Document
acs:gpdb:{#regionId}:{#accountId}:document/{#DBInstanceId}
    none
none

Request parameters

ParameterTypeRequiredDescriptionExample
DBInstanceIdstringYes

Instance ID.

Note You can call the DescribeDBInstances API to view details of all AnalyticDB for PostgreSQL instances in the target region, including the instance ID.
gp-xxxxxxxxx
NamespacestringNo

Namespace, default is public.

Note You can create a namespace using the CreateNamespace API and view the list of namespaces using the ListNamespaces API.
mynamespace
CollectionstringYes

Document collection name.

Note Created by the CreateDocumentCollection API. You can use the ListDocumentCollections API to view the list of created document collections.
document
RegionIdstringYes

The region ID where the instance is located.

cn-hangzhou
NamespacePasswordstringYes

Password for the namespace.

Note This value is specified in the CreateNamespace API.
testpassword
ContentstringNo

Text content for retrieval.

What is ADBPG?
FilterstringNo

Filter condition for the data to be queried, in SQL WHERE format. It is an expression that returns a boolean value (true or false). The conditions can be simple comparison operators such as equal (=), not equal (<> or !=), greater than (>), less than (<), greater than or equal to (>=), less than or equal to (<=), or more complex expressions combined with logical operators (AND, OR, NOT), and conditions using keywords like IN, BETWEEN, LIKE, etc.

Note
  • For detailed syntax, refer to: https://www.postgresqltutorial.com/postgresql-tutorial/postgresql-where/
  • title = 'test' AND name like 'test%'
    RecallWindowarrayNo

    Recall window. When this value is not empty, it adds context to the returned search results. The format is an array of 2 elements: List<A, B>, where -10 <= A <= 0 and 0 <= B <= 10.

    Note
  • Recommended when documents are fragmented and retrieval may lose contextual information.
  • Re-ranking takes precedence over windowing, i.e., re-rank first, then apply windowing.
  • integerNo

    Recall window size.

    [-5, 5]
    TopKintegerNo

    The number of the returned top results.

    10
    RerankFactordoubleNo

    Re-ranking factor. When this value is not empty, it will re-rank the vector search results. The value range is 1 < RerankFactor <= 5.

    Note
  • Re-ranking is slower when documents are sparsely split.
  • It is recommended that the re-ranked count (TopK * Factor, rounded up) does not exceed 50.
  • 2
    UseFullTextRetrievalbooleanNo

    Whether to use full-text retrieval (dual recall). Default is false, which means only vector retrieval is used.

    true
    MetricsstringNo

    Similarity algorithm used during retrieval. If this value is empty, the algorithm specified at the time of knowledge base creation is used. It is recommended not to set this unless there is a specific need.

    Note Value description:
  • l2: Euclidean distance.
  • ip: Inner product (dot product) distance.
  • cosine: Cosine similarity.
  • cosine
    FileNamestringNo

    In image search scenarios, the source file name of the image to be searched.

    Note The image file must have a file extension. Currently supported image extensions: bmp, jpg, jpeg, png, tiff.
    test.jpg
    FileUrlstringNo

    In image search scenarios, the publicly accessible URL of the image file.

    Note The image file must have a file extension. Currently supported image extensions: bmp, jpg, jpeg, png, tiff.
    https://xx/myImage.jpg
    IncludeVectorbooleanNo

    Whether to return vectors. Default is false.

    Note
  • false: Do not return vectors.
  • true: Return vectors.
  • true
    HybridSearchstringNo

    Dual recall algorithm, default is empty (i.e., directly compare and sort the scores of vectors and full text).

    Available values:

    • RRF: Reciprocal rank fusion, with a parameter k controlling the fusion effect. See HybridSearchArgs configuration for details;
    • Weight: Weighted ranking, using a parameter alpha to control the weight of vector and full-text scores, then sorting. See HybridSearchArgs configuration for details;
    • Cascaded: Perform full-text retrieval first, then vector retrieval on top of it;
    RRF
    HybridSearchArgsobjectNo

    The parameters of the two-way retrieval algorithm. The following parameters are supported:

    • When HybridSearch is set to RRF, the scores are calculated by using the 1/(k+rank_i) formula. The constant k is a positive integer that is greater than 1.
    { 
       "RRF": {
        "k": 60
       }
    }
    
    • When HybridSearch is set to Weight, the scores are calculated by using the alpha * vector_score + (1-alpha) * text_score formula. The alpha parameter specifies the proportion of the vector search score and the full-text search score and ranges from 0 to 1. A value of 0 specifies full-text search and a value of 1 specifies vector search.
    { 
       "Weight": {
        "alpha": 0.5
       }
    }
    
    objectNo

    The two-way retrieval parameters.

    anyNo

    The parameter values.

    { "RRF": { "k": 60 } }
    IncludeMetadataFieldsstringNo

    The metadata fields to be returned. Separate multiple fields with commas (,). This parameter is empty by default.

    title,page
    IncludeFileUrlbooleanNo

    Specifies whether to return the URL of the document. Default value: false.

    false
    UrlExpirationstringNo

    The validity period of the returned image URL.

    Note Value Description
    • Supported units are seconds (s) and days (d). For example, 300s specifies that the URL is valid for 300 seconds, and 60d specifies that the URL is valid for 60 days.

    • Valid values: 60s to 365d.

    • Default value: 7200s, that is, 2 hours.

    7200s
    GraphEnhancebooleanNo

    Whether to enable knowledge graph enhancement. Default value: false.

    false
    GraphSearchArgsobjectNo

    The search parameters of the knowledge graph.

    GraphTopKintegerNo

    The number of top entities and relationship edges. Default value: 60.

    60
    OrderBystringNo

    The fields by which to sort the results. This parameter is empty by default.

    The field must be either a metadata field or a default field in the table (e.g., id). Supported formats include:

    Single field, such as chunk_id. Multiple fields that are separated by commas (,), such as block_id,chunk_id. Descending order is supported, e.g., block_id DESC, chunk_id DESC.

    created_at
    OffsetintegerNo

    Offset, used for paginated queries.

    0

    Response parameters

    ParameterTypeDescriptionExample
    object
    RequestIdstring

    The request ID.

    ABB39CC3-4488-4857-905D-2E4A051D0521
    Messagestring

    Return message.

    success
    Statusstring

    The execution state of the operation. Valid values:

    • false: The operation fails.
    • true: The operation is successful.
    success
    Matchesarray<object>

    The retrieved data.

    MatchListobject

    The retrieved data.

    Idstring

    The unique ID of the vector data.

    doca-1234
    Contentstring

    The content that is used for full-text search. If you leave this parameter empty, only vector search is used. If you do not leave this parameter empty, two-way retrieval based on vector search and full-text search is used.

    Note You must specify at least one of the Content and Vector parameters.
    Cloud-native data warehouse AnalyticDB PostgreSQL Edition provides a simple, fast, and cost-effective PB-level cloud data warehouse solution.
    Metadataobject

    The metadata.

    string

    The metadata.

    {"title":"test"}
    Vectorarray

    The vector data. The length of the value must be the same as that of the Dimension parameter in the CreateCollection operation.

    Note If you leave this parameter empty, only full-text search results are returned.
    VectorListdouble

    The vector data. The length of the value must be the same as that of the Dimension parameter in the CreateCollection operation.

    Note If you leave this parameter empty, only full-text search results are returned.
    [1.2123,-0.12314,...]
    FileNamestring

    The name of the document.

    Note You can call the ListDocuments operation to query a list of documents.
    my_doc.txt
    Scoredouble

    The similarity score of the data. It is related to the l2, ip, or cosine algorithm that is specified when you create an index.

    0.12345
    RetrievalSourceinteger

    Source of the retrieval results:

    • 1 indicates vector retrieval
    • 2 indicates full-text retrieval
    • 3 indicates dual-path recall
    1
    LoaderMetadatastring

    Metadata during document loader loading.

    {"page_pos": 1}
    FileURLstring

    The public URL of the query result image, valid for 2 hours

    https://xxx-cn-beijing.aliyuncs.com/image/test.png
    RerankScoredouble

    Re-ranking score.

    6.2345
    WindowMatchesarray<object>

    List of windowed matches.

    windowMatchesobject
    WindowMatcharray<object>

    List of individual top windowed matches.

    windowMatchobject
    Idstring

    Unique ID of the vector data.

    doca-2345
    Contentstring

    Text content.

    AnalyticDB for PostgreSQL is a cloud-native data warehouse service that provides large-scale parallel processing (MPP) capabilities for massive online data analysis.
    Metadataobject

    Metadata map.

    string

    Metadata.

    {"title":"test"}
    FileNamestring

    File name.

    my_doc.txt
    LoaderMetadatastring

    Metadata information when the document loader was loaded.

    {"page_pos": 2}
    EmbeddingTokensstring

    Number of tokens used for vectorization.

    Note A token refers to the smallest unit into which the input text is divided; a token can be a word, a phrase, a punctuation mark, or a character, etc.
    100
    Usageobject

    Resource usage for this query.

    EmbeddingTokensstring

    Number of tokens used for vectorization.

    Note A token refers to the smallest unit into which the input text is divided; a token can be a word, a phrase, a punctuation mark, or a character, etc.
    100
    EmbeddingEntriesstring

    The number of entries used for vectorization.

    Note An entry refers to the number of processing items when performing vectorization on text or images. For example, processing one piece of text counts as 1 entry, while processing one image counts as 2 entries.
    10
    Entitiesarray<object>

    The entities.

    entitiesobject

    The details of the entity.

    Idstring

    The entity ID.

    1
    Entitystring

    The entity name.

    Dr. Wang
    Typestring

    The entity type.

    Figure
    Descriptionstring

    Entity description.

    A former advisor at DeepMind.
    FileNamestring

    The file name.

    my_doc.txt
    Relationsarray<object>

    The list of relationship edges.

    relationsobject

    The details of the relationship edge.

    Idstring

    The ID of the relationship edge.

    1
    SourceEntitystring

    The source entity.

    Former DeepMind consultant
    TargetEntitystring

    The destination entity.

    Dr. Wang
    Descriptionstring

    The description of the relationship edge.

    Dr. Wang previously served as an advisor at DeepMind.
    FileNamestring

    The file name.

    my_doc.txt

    Examples

    Sample success responses

    JSONformat

    {
      "RequestId": "ABB39CC3-4488-4857-905D-2E4A051D0521",
      "Message": "success",
      "Status": "success",
      "Matches": {
        "MatchList": [
          {
            "Id": "doca-1234",
            "Content": "Cloud-native data warehouse AnalyticDB PostgreSQL Edition provides a simple, fast, and cost-effective PB-level cloud data warehouse solution.",
            "Metadata": {
              "key": {
                "title": "test"
              }
            },
            "Vector": {
              "VectorList": [
                0
              ]
            },
            "FileName": "my_doc.txt",
            "Score": 0.12345,
            "RetrievalSource": 1,
            "LoaderMetadata": {
              "page_pos": 1
            },
            "FileURL": "https://xxx-cn-beijing.aliyuncs.com/image/test.png",
            "RerankScore": 6.2345
          }
        ]
      },
      "WindowMatches": {
        "windowMatches": [
          {
            "WindowMatch": {
              "windowMatch": [
                {
                  "Id": "doca-2345",
                  "Content": "AnalyticDB for PostgreSQL is a cloud-native data warehouse service that provides large-scale parallel processing (MPP) capabilities for massive online data analysis.",
                  "Metadata": {
                    "key": {
                      "title": "test"
                    }
                  },
                  "FileName": "my_doc.txt",
                  "LoaderMetadata": {
                    "page_pos": 2
                  }
                }
              ]
            }
          }
        ]
      },
      "EmbeddingTokens": 100,
      "Usage": {
        "EmbeddingTokens": 100,
        "EmbeddingEntries": 10
      },
      "Entities": {
        "entities": [
          {
            "Id": 1,
            "Entity": "Dr. Wang",
            "Type": "Figure\n",
            "Description": "A former advisor at DeepMind.",
            "FileName": "my_doc.txt"
          }
        ]
      },
      "Relations": {
        "relations": [
          {
            "Id": 1,
            "SourceEntity": "Former DeepMind consultant\n",
            "TargetEntity": "Dr. Wang",
            "Description": "Dr. Wang previously served as an advisor at DeepMind.",
            "FileName": "my_doc.txt\n"
          }
        ]
      }
    }

    Error codes

    For a list of error codes, visit the Service error codes.

    Change history

    Change timeSummary of changesOperation
    2024-07-18The request parameters of the API has changedView Change Details
    2024-04-29The request parameters of the API has changedView Change Details
    2024-04-22The request parameters of the API has changedView Change Details
    2024-02-19The request parameters of the API has changed. The response structure of the API has changedView Change Details
    2024-01-17The request parameters of the API has changed. The response structure of the API has changedView Change Details