The summary clause

Description

You can use the summary clause in a query statement to perform the following operations:

• Perform only a second-stage query to retrieve a summary. The engine provides three methods to retrieve a summary: by docid, by PK hash value, or by original PK value.

• Specify fields for a dynamic summary.

• Specify highlighting configurations.

Syntax

{ 
  "summary" : {
  }
}

Perform only a second-stage query

Get a summary by docid

{ 
  "config" : {
    "fetch_summary_type" : "docid"
  },
  "summary" : {
    "gids" : [
        "daogou|6|0|0|0|00000000000000004cd645cfd1c63041|184140777",
        "daogou|6|0|0|1|00000000000000005b3ceae33e5ab800|184140777"
    ]
  }
}

Set `fetch_summary_type` to `docid` in the config clause. Then, in the summary clause, specify the `gids` for the summaries that you want to retrieve. You do not need to know the specific meaning of a `gid`. You can retrieve the `gid` from the first-stage query results.

Get a summary by PK hash value

Retrieving a summary by PK hash value is similar to the docid method. This method also uses `gids` to specify the documents. The differences are as follows:

• Set `fetch_summary_type` to `pk` in the config clause.

• Although both methods use `gids`, PKs and `docids` are different. A PK uniquely identifies a document, but a `docid` does not. Therefore, when you use the `docid` method, you must also use the full and incremental version numbers to locate the document. When you use the PK method, you can ignore the version information. The `full version`, `incremental version`, and `docid` fields in the `gid` have no effect.

• To retrieve a summary by PK hash value, you must configure a primary key index in the schema of the cluster and set `has_primary_key_attribute` to `true`.

Example:

{ 
  "config" : {
    "fetch_summary_type" : "pk"
  },
  "summary" : {
    "gids" : [
        "daogou|6|100|100|100|00000000000000004cd645cfd1c63041|184140777",
        "daogou|6|200|200|200|00000000000000005b3ceae33e5ab800|184140777"
    ]
  }
}

Get a summary by original PK value

This method is different from the previous two because it does not use `gids`. Instead, it uses the original value of the document's PK to locate the document. To retrieve a summary this way, you must perform the following steps:

• Set `fetch_summary_type` to `rawpk` in the config clause.

• You must configure a primary key index in the schema of the destination cluster. The `hash` field configured for the cluster must be the same as the primary key field.

Example:

{ 
  "config" : {
    "fetch_summary_type" : "rawpk"
  },
  "summary" : {
    "gids" : [
        "cluster1:pk1,pk2",
				"cluster2:pk3,pk4"
    ]
  }
}


config=fetch_summary_type:rawpk&&fetch_summary=cluster1:pk1,pk2;cluster2:pk3,pk4


Note: The original PK value can contain any character. Some characters may conflict with the reserved characters in the query string.
You must escape all reserved characters in the query string by adding a backslash (\) before them.
The characters that require escaping are: comma (,), colon (:), semicolon (;), ampersand (&), equals sign (=), and the backslash character itself (\). 
For example, if the original PK value is abc,d:e\, you must escape it as abc\,d\:e\\ when you send it to the engine.

Specify fields for a dynamic summary

Use `fetch_fields` to specify the fields to display in the dynamic summary.

Example:

{
  "summary" : {
    "fetch_fields" : ["title", "body", "price"]
  }
}

Specify a highlighting configuration

Use the `highlight` parameter to configure highlighting for a dynamic summary:

• `highlighter`: the name of the highlighter to use.

• `pre_tag`: the prefix tag for highlighting.

• `post_tag`: the suffix tag for highlighting.

• `fields`: the fields to highlight.

  • `fragment_size`: the length of the fragment.

  • `number_of_fragments`: the number of fragments.

Example:

{
  "summary" : {
    "highlight" : {
      "highlighter" : "plain",
      "pre_tag" : "",
      "post_tag" : "",
      "fields" : {
        "title" : {
          "fragment_size" : 100,
          "number_of_fragments" : 3
        }
      }
    }
  }
}

Notes

• The `summary` clause is optional.

• A summary may not be found during retrieval. This can happen if the cluster is unstable, which causes the retrieval to time out. It can also happen during real-time data updates when the document is temporarily deleted. This is because data updates are performed by first deleting the old document and then adding the new one.

• Avoid retrieving summaries by `docid`. The `docid` value is not static and can change during incremental switches or real-time data updates.