Search Requests

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')).