execute a search query

Game version to utilise for this query.

A query string for searching excel data.

Queries are formed of clauses, which take the basic form of [specifier][operation][value], i.e. Name="Example". Multiple clauses may be specified by seperating them with whitespace, i.e. Foo=1 Bar=2.

Like field filters, clause specifiers may use dot notation to specify fields inside structs and relations (i.e. Foo.Bar=1), as well as language tags to target fields in particular languages (i.e. Foo@ja=1).

Arrays must be selected explicitly (i.e. Foo[]=1), resulting in a match for any value within the array. An index can be used to reduce the search space (i.e. Foo[1]=1).

By default, results will match at least one clause, with higher relevance scores for those that match more. To modify this behavior, clauses can decorated. +clause specifies that the clause must be matched for any result returned, and -clause specifies that it must not be matched.

To represent more involved boolean matching, clauses may be grouped with parentheses. +(a b) +c will require that either clauses a or b must match, in addition to c matching.

Supported operations:

• partial string match: key~"value"

• exact equality: key=value

• numeric comparison: key>=value, key>value, key<=value, key<value

Supported value types:

• string: "example"

• number: 1, -1, 1.0

• boolean: true, false

List of excel sheets that the query should be run against. At least one must be specified if not querying a cursor.

Continuation token to retrieve further results from a prior search request. If specified, takes priority over query.

Maximum number of rows to return. To paginate, provide the cursor token provided in next to the cursor parameter.

Known languages supported by the game data format. NOTE: Not all languages that are supported by the format are valid for all editions of the game. For example, the global game client acknowledges the existence of chs and kr, however does not provide any data for them.

A filter string for selecting fields within a row.

Filters are comprised of a comma-seperated list of field paths, i.e. a,b will select the fields a and b.

Decorators may be used to modify the way a field is read. They take the form of @decorator(arguments), i.e. field@lang(en). Currently accepted decorators:

• @lang(<language>): Overrides the query's language for the decorated field. Allows one query to access data for multiple languages. language accepts any valid LanguageString.

• @as(<format>): Overrides the default output format for the decorated field.

Currently accepted formats for @as:

• raw: Prevents further processing, such as sheet relations, being performed on the decorated field. Has no effect on regular scalar fields.

• html: Formats a string field as rich HTML. Invalid on non-string fields. Output will be a valid HTML fragment, however no stability guarantees are made over the precise markup used.

Nested fields may be selected using dot notation, i.e. a.b will select the field b contained in the struct a.

Arrays must be targeted if selecting fields within them, i.e. a[].b will select all b fields of structs within the array a, however a.b will select nothing.

A filter string for selecting fields within a row.

Filters are comprised of a comma-seperated list of field paths, i.e. a,b will select the fields a and b.

Decorators may be used to modify the way a field is read. They take the form of @decorator(arguments), i.e. field@lang(en). Currently accepted decorators:

• @lang(<language>): Overrides the query's language for the decorated field. Allows one query to access data for multiple languages. language accepts any valid LanguageString.

• @as(<format>): Overrides the default output format for the decorated field.

Currently accepted formats for @as:

• raw: Prevents further processing, such as sheet relations, being performed on the decorated field. Has no effect on regular scalar fields.

• html: Formats a string field as rich HTML. Invalid on non-string fields. Output will be a valid HTML fragment, however no stability guarantees are made over the precise markup used.

Nested fields may be selected using dot notation, i.e. a.b will select the field b contained in the struct a.

Arrays must be targeted if selecting fields within them, i.e. a[].b will select all b fields of structs within the array a, however a.b will select nothing.