> ## Documentation Index
> Fetch the complete documentation index at: https://docs.loqate.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Query Process

## Overview

The Query process is designed to perform SQL-like custom queries on the Loqate GKR. It enables searching and retrieving multiple results of specific address components that meet user-definable conditions. The query-conditions are expressed in our proprietary query-language, an example using our Verify SaaS service and the syntax and semantics are described below.

```json theme={null}
{
  "Key": "{{LoqateKey}}",
  "Options": {
    "Process": "Query",
    "ServerOptions": {
      "Table": "rd_US_vfy",
      "QueryString": "(PostalCodePrimary LIKE \"60010%*\")",
      "OutputFields": "Locality",
      "QueryClause": "Distinct",
      "AliasPreference": "First",
      "RangefieldPreference": "Match",
      "MaxResults": 655
    }
  }
}
```

Query is a debug tool to be used to support submission of support cases, and please note this tool is in maintenance mode with no planned future developments or bug fixes.

## Query Syntax and Semantics

A query has the following syntax:

```
...(<(>QUERY-EXPRESSION <LOGICAL-OPERATOR QUERY-EXPRESSION><)> <LOGICAL-OPERATOR QUERY-EXPRESSION<)>...
```

The terminology used in the query syntax is described below. Parenthesis may be used optionally to nest and string simple queries into compound queries:

| Term                | Syntax/Values                                     | Description                                                               |
| ------------------- | ------------------------------------------------- | ------------------------------------------------------------------------- |
| PREFIX TAG          | `~`                                               | Means phonetic similarity (optional)                                      |
| SUFFIX TAG          | `%`, `*`                                          | `%` means auto-complete word, `*` means auto-complete phrase              |
| QUERY-KEYWORD       | `<PREFIX-TAG(s)>word<SUFFIX-TAG(s)>`              | Tags apply at word level to qualify search criteria                       |
| CONDITION-OPERATORS | `LIKE`, `CONTAINS`                                | `LIKE` = Ordered-matching, `CONTAINS` = Unordered-matching                |
| QUERY-EXPRESSION    | `FieldName CONDITION-OPERATOR "QUERY-KEYWORD(s)"` | Complete query expression                                                 |
| LOGICAL-OPERATORS   | Two pipes, `&&`                                   | Two pipes = logical OR, `&&` = logical AND, used to form compound queries |

## Example Queries

| Query                                                           | Matches                                                               | Does Not Match                |
| --------------------------------------------------------------- | --------------------------------------------------------------------- | ----------------------------- |
| `Thoroughfare LIKE "Bayhill Dr"`                                | `Bayhill Dr`                                                          | `Dr Bayhill`, `Bayhill Drive` |
| `Thoroughfare CONTAINS "Bayhill Dr"`                            | `Bayhill Dr`, `Dr Bayhill`                                            | `Bayhill Drive`               |
| `Thoroughfare LIKE "~Payhill Dr"`                               | `Bayhill Dr`                                                          | `Bayhill Tr`                  |
| `Thoroughfare CONTAINS "Bay% Dr"`                               | `Dr Bayhill`, `Bayhill Dr`, `Bay Dr`                                  | `Bay Drive`, `TromBay Dr`     |
| `Thoroughfare LIKE "Bay Dr%"`                                   | `Bay Dr`, `Bay Drive`                                                 | `Bayhill Dr`, `Bay Drive Ct`  |
| `Thoroughfare LIKE "Bay Dr%*"`                                  | `Bay Dr`, `Bay Dr Ct`, `Bay Drive`, `Bay Drive Ct`                    |                               |
| `(Thoroughfare CONTAINS "Bay%") && (Locality LIKE "San Bruno")` | `Bayhill Drive San Bruno`, `Bay Dr San Bruno`, `Bayhill Dr San Bruno` |                               |

## Process Options

The query tool uses the following process options:

| Option                 | Required | Description                                                                                                                                                                                                                                                                                                    |
| ---------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Table`                | Required | Reference (GKR) table to be queried                                                                                                                                                                                                                                                                            |
| `QueryString`          | Required | String expressing the query in the query language                                                                                                                                                                                                                                                              |
| `OutputFields`         | Optional | Comma separated output field-names desired. Field-names are case sensitive. Reserved keyword `ALL` (or null) returns all field in output.                                                                                                                                                                      |
| `MaxResults`           | Optional | Max number of output records desired. Defaults to `10`, valid values are 1-1000.                                                                                                                                                                                                                               |
| `QueryClause`          | Optional | `DISTINCT`/`UNIQUE`/null specifies output address component-set to be distinct, unique, or unconstrained across the output record results, respectively.                                                                                                                                                       |
| `AliasPreference`      | Optional | Specify to return, for non-rangefields: `FIRST` - the first alias in fields desired in the output; `EXHAUSTIVE` - all combinations of every alias; `UNPROCESSED` (null) - field-value entry as stored in the GKR                                                                                               |
| `RangefieldPreference` | Optional | Specify to return, for rangefields: `MATCH` - the queried value verified in the range; `RANGE` - the range containing the queried value after verification; `FULL` - every value in the range containing the queried value; `RAW` (null) - the range-field containing the queried value as stored in the table |

## Output

The results of the query are returned in the `ProcessResult` object.