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.

{
    "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:

PREFIX TAG (optional): ~ means phonetic similarity

SUFFIX TAG: % means auto-complete word, * means auto-complete phrase

The tags apply at the word level and qualify the search criteria:

QUERY-KEYWORD:  <PREFIX-TAG(s)>word<SUFFIX-TAG(s)> 

CONDITION-OPERATORS: LIKE (Ordered-matching), CONTAINS (Unordered-matching)

QUERY-EXPRESSION : FieldName CONDITION-OPERATOR “QUERY-KEYWORD(s)” 

LOGICAL-OPERATORS: || (logical OR), && (logical AND), used to form compound queries by stringing multiple QUERY-EXPRESSIONs

Example Queries:

Thoroughfare LIKE “Bayhill Dr” matches Bayhill Dr but does not match Dr Bayhill or Bayhill Drive

• Thoroughfare CONTAINS “Bayhill Dr” matches Bayhill Dr and Dr Bayhill but does not match Bayhill Drive
• Thoroughfare LIKE “~Payhill Dr” matches Bayhill Dr but does not match Bayhill Tr
• Thoroughfare CONTAINS “Bay% Dr” matches Dr Bayhill, Bayhill Dr and Bay Dr, but does not match Bay Drive or TromBay Dr
• Thoroughfare LIKE “Bay Dr%” matches Bay Dr and Bay Drive but does not match Bayhill Dr or Bay Drive Ct
• Thoroughfare LIKE “Bay Dr%*” matches Bay Dr, Bay Dr Ct, Bay Drive and Bay Drive Ct
• (Thoroughfare CONTAINS “Bay%”) && (Locality LIKE “San Bruno”) matches Bayhill Drive San Bruno, Bay Dr San Bruno and Bayhill Dr San Bruno
  

 

Process Options

The query tool uses the following process options:

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.