Search & Paging Syntax

Data retrieval services typically include standard parameters for searching, sorting, and pagination.

1. Pagination Parameters
2. Sort Parameters
3. Search Parameters
4. Data Types
   1. Date
   2. Datetime
   3. Time
   4. Integer
   5. Decimal
   6. Character
   7. Boolean
   8. NULL
5. Functions
6. SparkQL Errors

Pagination Parameters

Pagination allows data to be retrieved in sets of a specified size and provides additional data about the result set.

When the Pagination hash is enabled, the response will include the following:

"Pagination": {
  "TotalRows": 78,
  "PageSize": 25,
  "TotalPages": 4,
  "CurrentPage": 1
}

Sort Parameters

Sorting is typically available on resources that allow searching.

Any searchable field can be present in the _orderby parameter, with some exceptions (e.g. longer text fields such as PublicRemarks for listings). To specify "Ascending" or "Descending" order, prefix the field used in the _orderby parameter with the+ and - characters, respectively.

Ordering listing results descending by ListPrice

_orderby=-ListPrice

Ordering listing results by multiple attributes:

_orderby=-ListPrice,+BathsTotal

Search Parameters

Request parameters below are common to data retrieval services supporting searching.

The components of a filter string are as follows:

• connector: used to indicate AND, OR, or NOT operators between multiple fields.

• field: a valid field name for the resource being searched, e.g. ListPrice for listing standard field data, or "Contract Information"."Area" for listing custom field data.
• operator: One of the following:

• condition: a value of a supported data type, or a function supported by the data type.

_filter supports one level of parameter nesting with parentheses. Valid query with one level of nesting:

Field1 Eq 'Value1' And (Field2 Eq 'Value2' Or Field3 Eq 'Value3')

Invalid query with two levels of nesting:

Field1 Eq 'Value1' And (Field2 Eq 'Value2' Or (Field3 Eq 'Value3' And Field4 Eq 'Value4'))

Data Types

All data values are one of the following defined data types.

Date

Example: 2008-10-31

Datetime

Example: 2003-04-01T19:01:02Z

Time

Example: 19:01:02

Integer

Example: 142

The Integer data type specifies a number with no decimal component.

Decimal

Example: 142.01

The Decimal data type specifies a number with a decimal component.

Character

Example: 'Lorem O\'Little Ipsum'

The Character data type specifies a string, and is always padded with single quotes.

Wildcards

The Character data type supports the following two wildcard operators:

Note the following restrictions on using wildcards:

1. A condition may not exist solely of wildcards.
2. A condition may not include more than three wildcard operators.
3. Wildcards may only be used with the Eq and Ne operators.

Escaping Special Characters

Any special character (wildcards or a single quote) can be escaped with the backslash character:

'Lorem O\'Little Ipsum'

Boolean

Example: true

Boolean data types are always either true or false.

NULL

Example: NULL

NULL describes the absence of a value. There are only two use cases for searching using the NULL type:

1. For the absense of a value, e.g. City Eq NULL
2. For the precense of a value, e.g. City Ne NULL

Functions

Functions may be used in place of data values for supported data types to provide more flexible searches.

SparkQL Errors

To help with debugging errors when searching, a SparkQLErrors attribute is included in responses that fail due to an invalid _filter parameter. See the response description documentation for more details.