Search Requests | ASN Toolkit

Search Syntax

GET ../search

Search Request Parameters

Name	Description	Required
`bq`	One or more match expressions that define a Boolean search. Multiple expressions are joined with a top-level `AND`. If the `bq` parameter is specified in conjunction with the `q` parameter, the values are joined with a top-level `AND`. Within a match expression, you can use the `-` (NOT), `\|` (OR), and `` (wildcard) operators to exclude particular terms, find results that match any of the specified terms, or search for a prefix. To search for a phrase rather than individual terms, you can enclose the phrase in double quotes. For more information, see ASN Search* Documentation. Condition: Required if the `q` parameter is not specified. Type: String	Conditional
`facet`	A comma-separated list of the fields for which you want to compute facets. The specified fields must be numeric fields or defined as facet-enabled in the domain configuration. By default, counts are computed for all field values. If you want to specify the field values that you want counted for a particular field, use the `facet-FIELD-constraints` parameter instead, where `FIELD` is the name of the field. You can specify the maximum number of constraints to include in the results with the `facet-FIELD-top-n` parameter. By default, the results include counts for the top 40 constraints. Type: String	No
`facet-FIELD-constraints`	The field values (facet constraints) that you want to count for a particular field. `FIELD` is the name of the field. Constraints are specified as a comma-separated list of ranges or single-quoted strings. For example, `facet-year-constraints=2000..2011` calculates facet counts for the years 2000 through 2011, inclusive. You can omit the lower end of a range to count all of the values less than or equal to the specified value. Similarly, you can omit the upper end of a range to count all of the values greater than or equal to the specified value. To specify constraints for a text field, enclose the values in single quotes. For example, `facet-color-constraints='red','blue','green'.`If you don't specify facet constraints, counts are computed for all field values. Type: String	No
`facet-FIELD-sort`	How you want to sort facet values for a particular field. `FIELD` is the name of the field. There are four sorting options: `alpha`—Sort the facet values alphabetically (in ascending order). `count`—Sort the facet values by their counts (in descending order). `max`—Sort the facet values according to the maximum values in the specified field. This option is specified as `max(FIELD)`. By default, the facet values are sorted in ascending order. To sort in descending order, prefix the sort option with - (minus): `-max(FIELD)`. `sum`—Sort the facet values according to the sum of the values in the specified field (in ascending order). This option is specified as `sum(FIELD)`. Type: String	No
`facet-FIELD-top-n`	Set the maximum number of facet constraints to be included for the specified field in the search results. By default, the results include counts for the top 40 constraints. Type: Integer	No
`q`	The string to search for. You use the `q` parameter to perform simple text searches. This searches the default search field for the specified text. If the `q` parameter is specified in conjunction with the `bq` parameter, the values are joined with a top-level `AND`. If you separate search terms with plus (+) or a space, ASN Search matches documents that contain all of the specified search terms—they are ANDed together. For example, `q=star+wars` searches the default field for star and wars. This is equivalent to specifying `bq='star wars'`. You can use the `-` (NOT), `\|` (OR), and `` (wildcard) operators to exclude particular terms, find results that match any of the specified terms, or search for a prefix. To search for a phrase rather than individual terms, you can enclose the phrase in double quotes. For more information, see ASN Search* Documentation. Condition: Required if the `bq` parameter is not specified. Type: String	Conditional
`rank`	A comma-separated list of fields or rank expressions to use for ranking. A maximum of 10 fields and rank expressions can be specified. You can use any uint field to rank results numerically. Any result-enabled text or literal field can be used to rank results alphabetically. To rank results by relevance, you can specify the name of a custom rank expression or `text_relevance`. Hits are ordered according to the specified rank field(s). By default, hits are ranked in ascending order. You can prefix a field name with a minus (-) to rank in descending order. If no rank parameter is specified, it defaults to `rank=-text_relevance`, which lists results according to their text_relevance scores with the highest-scoring documents first. Type: String	No
`results-type`	Controls the content type of the response, `json` or `xml`. The default is `json`. Type: String	No
`return-fields`	The document fields to include in the response. Up to 2 KB of data can be returned from a text field. If the field contents exceed 2 KB, only the first 2 KB is included in the results. Specified as a comma-separated list of field names. If no return-fields are specified, only the document ids of the hits are returned. Type: String	No
`size`	The maximum number of search hits to return. The default is 10. Type: Positive Integer	No
`start`	The offset of the first search hit you want to return. The default is 0 (the first hit). Type: Positive Integer	No
`t-FIELD`	Restrict the match set used in subsequent post-processing steps according to the specified rank expression. Only hits that have a score within the specified RANGE are included. Ranges are specified as described in Expression Syntax for Boolean Queries below. Type: RANGE	No

Expression Syntax for Boolean Queries

Expression Syntax	Description
`FIELD:'search string'`	Search for a string in the specified text or literal field. For example, `bq=description:'read'`. Any single quotation marks or backslashes in the string must be escaped with a backslash.
`(field FIELD 'search string')`	Search for a string in the specified text or literal field. For example, `(field description 'read')`. Any single quotation marks or backslashes in the string must be escaped with a backslash. You can use this alternate fielded search syntax when you're specifying multiple fielded search expressions as part of Boolean expression. For example, `bq=(and (field description 'read') (filter date_valid ..2000))`.
`FIELD:value`	Search for an integer value in the specified uint field. For example, `bq=date_valid:2000`. Matches documents that have at least one value in the field that equals the specifed value. You can specify a single value or a range of values. A pair of nonnegative integers separated by two dots matches documents that have at least one attribute in the field that falls in the specified range. You can omit one value to specify an open-ended upper or lower limit. The range is inclusive on both ends. For example, `bq=date_valid:1998..2000`.
`(filter FIELD value)`	Search for an integer in the specified uint field. For example, `(filter date_valid 2000)`. Matches documents that have at least one value in the field that equals the specifed value. You can use this alternate fielded search syntax when you're specifying multiple fielded search expressions as part of Boolean expression. For example, `bq=(and (field description 'read') (filter date_valid ..2000))`. You can specify a single value or a range of values. A pair of nonnegative integers separated by two dots matches documents that have at least one attribute in the field that falls in the specified range. You can omit one value to specify an open-ended upper or lower limit. The range is inclusive on both ends. For example, `(filter date_valid 1998..2000)`.
`(and expression1 expression2 expressionN)`	Include hits only if they match all of the specified expressions. (Boolean `AND` operator.) For example, `bq=(and (field description 'read') (field statement_label 'Benchmark') (filter date_valid ..2000))`.
`(not expression1)`	Exclude hits that match the specified expression. (Boolean `NOT` operator.) For example, `bq=(not (and (field statement_label 'Benchmark') (field statement_label 'Standard')))`.
`(or expression1 expression2 expressionN)`	Include hits that match any of the specified expressions. (Boolean `OR` operator.) For example, `bq=(or (field statement_label 'Benchmark') (field statement_label 'Standard') (field statement_label 'Component'))`.