fetch_summary clause - OpenSearch - Alibaba Cloud Documentation Center

Overview

You can include a fetch_summary clause in a query statement to perform an independent phase-2 query. You can perform a phase-2 query to obtain summaries of the documents that you queried. OpenSearch Retrieval Engine Edition can obtain a summary of a document based on the specified document ID, the hash value of the primary key of the document, and the value of the primary key.

Syntax

Obtain summaries of documents based on specified document IDs

  config=fetch_summary_type:docid&&fetch_summary=gid[, gid]

You must set the value of the fetch_summary_type parameter to docid in the config clause and specify the gid values of the documents that you want to query in the fetch_summary clause. You can obtain the values of the gid parameter from the response of the corresponding phase-1 query.

Example:

config=format:xml,fetch_summary_type:docid,cluster:daogou&&query=test&&fetch_summary=daogou|6|0|0|0|00000000000000004cd645cfd1c63041|184140777,daogou|6|0|0|1|00000000000000005b3ceae33e5ab800|184140777 

Response:
<?xml version="1.0" encoding="UTF-8"?>
<Root>
<TotalTime>0.003</TotalTime>
<hits numhits="2" totalhits="0" coveredPercent="0.00">
<hit cluster_name="daogou" hash_id="0" docid="0" gid="daogou|6|0|0|0|00000000000000004cd645cfd1c63041|184140777">
<fields>
<id>1</id>
</fields>
<property>
</property>
<sortExprValues></sortExprValues>
</hit>
<hit cluster_name="daogou" hash_id="0" docid="1" gid="daogou|6|0|0|1|00000000000000005b3ceae33e5ab800|184140777">
<fields>
<id>2</id>
</fields>
<property>
</property>
<sortExprValues></sortExprValues>
</hit>
</hits>
<AggregateResults>
</AggregateResults>
<Error>
<ErrorCode>0</ErrorCode>
<ErrorDescription></ErrorDescription>
</Error>
</Root>

Note: In the response of each independent phase-2 query, the value of the totalhits parameter is 0 and the value of the coveredPercent parameter is 0.  The order of matched documents that are displayed in the value of the hits parameter is the same as the order of the values that you specified for the gid parameter in the fetch_summary clause. If you specify an invalid value for the hash_id or docId parameter, OpenSearch Retrieval Engine Edition cannot obtain a summary for the corresponding document. In this case, the value of the fields field that corresponds to the document is empty.

Obtain summaries of documents based on the hash values that are calculated based on the primary keys of the documents

The method that is used to obtain a summary of a document based on the hash value of the primary key of the document is similar to the method that is used to obtain a summary of a document based on the ID of the document. OpenSearch Retrieval Engine Edition performs the query based on the gid that you specified in the query statement. The following items describe the differences between the two methods:

If you want to obtain a summary of a document based on the hash value of the primary key of the document, set the value of the fetch_summary_type parameter to pk in the config clause.
Different values of the fetch_summary_type parameter specify different methods that can be used to identify documents. In most cases, you can use the primary key of a document to identify the document, but you cannot use only the ID of a document to identify the document. If you specify docid as the value of the fetch_summary_type parameter, OpenSearch Retrieval Engine Edition identifies a document based on the specified document ID and the version numbers of the full data and the incremental data. If you specify pk as the value of the fetch_summary_type parameter, OpenSearch Retrieval Engine Edition does not require version information to identify a document. If the value of the fetch_summary_type parameter is pk, OpenSearch Retrieval Engine Edition ignores the components that specify the document ID and the version numbers of the full data and the incremental data in each gid that you specified in the query statement.
If you want to obtain a summary of a document based on the hash value that is calculated based on the primary key of the document, specify a field as the primary key and set the value of the has_primary_key_attribute parameter to true in the schema of the cluster on which the document is stored.

Example:

config=fetch_summary_type:pk&&fetch_summary=daogou|6|100|100|100|00000000000000004cd645cfd1c63041|184140777,daogou|6|200|200|200|00000000000000005b3ceae33e5ab800|184140777

Obtain summaries of documents based on the primary key values of the documents

In this method, OpenSearch Retrieval Engine Edition does not identify a document based on the gid of the document. OpenSearch Retrieval Engine Edition identifies a document based on the primary key value of the document. If you want to use this method, perform the following operations:

Set the value of the fetch_summary_type parameter to rawpk in the config clause.
Specify a field as the primary key of documents in the schema of the cluster in which the documents are stored and make sure that the primary key field is the same as the value of the hash_field parameter.

Example:

config=fetch_summary_type:rawpk&&fetch_summary=cluster1:pk1,pk2;cluster2:pk3,pk4
Response:
<?xml version="1.0" encoding="UTF-8"?>
<Root>
<TotalTime>0.003</TotalTime>
<hits numhits="2" totalhits="0" coveredPercent="0.00">
<hit cluster_name="daogou" hash_id="17871" docid="0" gid="daogou|0|0|17871|0|4cd645cfd1c63041391f27d3272cfeeb|4294967295">
<fields>
<id>1</id>
</fields>
<property>
</property>
<sortExprValues></sortExprValues>
<raw_pk>111</raw_pk>
</hit>
<hit cluster_name="daogou" hash_id="60131" docid="0" gid="daogou|0|0|60131|0|5b3ceae33e5ab800352f040b4d9c05e9|4294967295">
<fields>
<id>2</id>
</fields>
<property>
</property>
<sortExprValues></sortExprValues>
<raw_pk>112</raw_pk>
</hit>
</hits>
<AggregateResults>
</AggregateResults>
<Error>
<ErrorCode>0</ErrorCode>
<ErrorDescription></ErrorDescription>
</Error>
</Root>

Note: In this example, cluster1 and cluster2 that are specified in the fetch_summary clause are the names of the clusters on which the search engine performs the query. The raw_pk field is included in the response that is returned. Values of the primary key field may contain special characters that are reserved by OpenSearch Retrieval Engine Edition for query statements. When you specify primary key values in the fetch_summary clause, add a backslash (\) before each reserved character to escape the character. The following characters must be escaped in the fetch_summary clause: commas (,), colons (:), semicolons (:), ampersands (&), equal signs (=), and backslashes (\).  For example, if a value of the primary key field is abc,d:e\, convert the value to abc\,d\:e\\.

Usage notes

A fetch_summary clause is optional.
Summary extraction failures may occur due to cluster instability and data updates. If the cluster on which the query is performed is unstable, summary extraction operations may time out. When the system updates data, the data of the documents that you want to obtain may be in the deleted state for a short period of time because the system updates data by deleting old data and then loading real-time data.
We recommend that you do not use the document ID-based method to obtain summaries because document IDs are not fixed values and may change after the system loads incremental data or updates real-time data.