Field Operators

AVAILABLE API VERSION
API v56.0 and later

Each field on the sObject has a corresponding input object field on the Filter type. The input object field has an Operators type. For example, Account has a field Name of type String, and so the AccountFilter input object has an input object field Name of type StringOperators.

1type Account {
2  Name: StringValue
3}
4
5input Account_Filter {
6  Name: StringOperators
7}

Each Operators type exposes the filtering capabilities of that field type. Each field type that supports filtering has a corresponding Operators type. The Operators type has one input object field for each filtering capability of the underlying data type. For example, the StringOperators type can compare String values based on equality and ordering.

If multiple operations are specified on an Operator, both operations are included in the query and AND’d together. For example, where: {AnnualRevenue: {gt: 10000, lt: 100000}} finds records with an annual revenue of more than 10000 and less than 100000.

Tip

GraphQL supports multiple operators in queries. See Boolean Operators for more information and examples.

Field Functions

Each field on the Operators type corresponds to the following functions.

Function	Description
`eq`	Equals. The expression is true if the field value equals the value in the expression. String comparisons are case-insensitive. For example, `Name: { eq: "Genepoint" }` returns the same result as `Name: { eq: "GenePoint" }`
`ne`	Not equals. The expression is true if the field value doesn’t equal the specified value.
`lt`	Less than. The expression is true if the field value is less than the specified value.
`gt`	Greater than. The expression is true if the field value is greater than the specified value.
`lte`	Less than or equal. The expression is true if the field value is less than, or equals, the specified value.
`gte`	Greater than or equal. The expression is true if the field value is greater than or equal to the specified value.
`like`	The expression is true if the field value matches the characters of the specified value. Supported for string fields only.
`in`	Is an element within a static set of items. For example, `Name: { in: ["Genepoint", "Edge Communications"] }`
`nin`	Is not an element within a static set of items
`inq`	Is an element in query. Use this function to create a semi-join filter.
`ninq`	Is not an element in query. Use this function to create an anti-join filter.

Fields on sObjects have corresponding mappings to Operators types. The main field types are:

String Field Types
- String
- Email
- PhoneNumber
- TextArea
- LongTextArea
- Url
Number Field Types
- Double
- Int
- Long
- Currency
- Percent
Date and Time Field Types
- Date
- DateTime
- Time
Other Types
- Boolean
- ID
- Picklist
- Multi-picklist
- Latitude
- Longitude
- Geolocation

These field types are discussed in the following sections.

String Field Types

Operators for field types Email, TextArea, LongTextArea, Url, and PhoneNumber are similar to StringOperators, but they use the appropriate scalar for the input object field type.

The like operator behaves similarly to the WHERE SOSL expression.

String Fields

String fields map to the StringOperators filter type.

1input StringOperators {
2  eq:   String
3  ne:   String
4  like: String
5  lt:   String
6  gt:   String
7  lte:  String
8  gte:  String
9  in:   [String]
10  nin:  [String]
11}

Email Fields

Email fields map to the EmailOperators filter type.

1input EmailOperators {
2  eq: Email
3  ne: Email
4  like: Email
5  lt: Email
6  gt: Email
7  lte: Email
8  gte: Email
9  in: [Email]
10  nin: [Email]
11}

PhoneNumber Fields

PhoneNumber fields map to the PhoneNumberOperators filter type.

1input PhoneNumberOperators {
2  eq: PhoneNumber
3  ne: PhoneNumber
4  like: PhoneNumber
5  lt: PhoneNumber
6  gt: PhoneNumber
7  lte: PhoneNumber
8  gte: PhoneNumber
9  in: [PhoneNumber]
10  nin: [PhoneNumber]
11}

TextArea Fields

TextArea fields map to the TextAreaOperators filter type.

1input TextAreaOperators {
2  eq: TextArea
3  ne: TextArea
4  like: TextArea
5  lt: TextArea
6  gt: TextArea
7  lte: TextArea
8  gte: TextArea
9  in: [TextArea]
10  nin: [TextArea]
11}

LongTextArea Fields

LongTextArea fields map to the LongTextAreaOperators filter type.

1input LongTextAreaOperators {
2  eq: LongTextArea
3  ne: LongTextArea
4  like: LongTextArea
5  lt: LongTextArea
6  gt: LongTextArea
7  lte: LongTextArea
8  gte: LongTextArea
9  in: [LongTextArea]
10  nin: [LongTextArea]
11}

Url Fields

Url fields map to the URLOperators filter type.

1input URLOperators {
2  eq: Url
3  ne: Url
4  like: Url
5  lt: Url
6  gt: Url
7  lte: Url
8  gte: Url
9  in: Url
10  nin: Url
11}

Number Field Types

Operators for field types Currency, Percent, Longitude, and Latitude are similar to DoubleOperators, but they use the appropriate scalar for the input object field type. The Operator for the Long field type is similar to IntegerOperators, but uses Long instead of Int.

Double Fields

Double fields map to the DoubleOperators filter type.

1input DoubleOperators {
2  eq:  Double
3  ne:  Double
4  lt:  Double
5  gt:  Double
6  lte: Double
7  gte: Double
8  in:  [Double]
9  nin: [Double]
10}

Int Fields

Int fields map to the IntegerOperators filter type.

1input IntegerOperators {
2  eq:  Int
3  ne:  Int
4  lt:  Int
5  gt:  Int
6  lte: Int
7  gte: Int
8  in:  [Int]
9  nin: [Int]
10}

Long Fields

Long fields map to the LongOperators filter type.

1input LongOperators {
2  eq: Long
3  ne: Long
4  lt: Long
5  gt: Long
6  lte: Long
7  gte: Long
8  in: [Long]
9  nin: [Long]
10}

Currency Fields

Currency fields map to the CurrencyOperators filter type.

1input CurrencyOperators {
2  eq: Currency
3  ne: Currency
4  lt: Currency
5  gt: Currency
6  lte: Currency
7  gte: Currency
8  in: [Currency]
9  nin: [Currency]
10}

Percent Fields

Percent fields map to the PercentOperators filter type.

1input PercentOperators {
2  eq: Percent
3  ne: Percent
4  lt: Percent
5  gt: Percent
6  lte: Percent
7  gte: Percent
8  in: [Percent]
9  nin: [Percent]
10}

Date, DateTime, and Time Field Types

Date and DateTime fields support additional filtering criteria beyond the standard set of operators defined on other types. Rather than the input object fields of the Operators type being the scalar type, they are of input object type DateInput and DateTimeInput respectively.

In addition to a different type for the individual operators, Date and DateTime Operators support additional functions related to the relative time of the field value. These input object field types are DateFunctionInput and DateTimeFunctionInput.

Date Fields

Date fields are mapped to DateOperators.

1input DateOperators {
2  eq:  DateInput
3  ne:  DateInput
4  lt:  DateInput
5  gt:  DateInput
6  lte: DateInput
7  gte: DateInput
8  in:  [DateInput]
9  nin: [DateInput]
10  CALENDAR_MONTH:   DateFunctionInput
11  CALENDAR_QUARTER: DateFunctionInput
12  CALENDAR_YEAR:    DateFunctionInput
13  DAY_IN_MONTH:     DateFunctionInput
14  DAY_IN_WEEK:      DateFunctionInput
15  DAY_IN_YEAR:      DateFunctionInput
16  FISCAL_MONTH:     DateFunctionInput
17  FISCAL_QUARTER:   DateFunctionInput
18  FISCAL_YEAR:      DateFunctionInput
19  WEEK_IN_MONTH:    DateFunctionInput
20  WEEK_IN_YEAR:     DateFunctionInput
21}

DateInput facilitates operating on Date fields by more than just the exact value of a particular Date.

1input DateInput {
2  value:   Date         # An exact Date value
3  literal: DATE_LITERAL # a literal value for a relative time
4  range:   DateRange    # a range of Dates
5}

Date literals represent a relative range of time, such as last month, this week, or next year. See SOQL and SOSL Reference: Date Formats and Date Literals in WHERE Clauses.

1enum DATE_LITERAL {
2  YESTERDAY
3  TODAY
4  TOMORROW
5  LAST_WEEK
6  THIS_WEEK
7  NEXT_WEEK
8  LAST_MONTH
9  THIS_MONTH
10  NEXT_MONTH
11  LAST_QUARTER
12  THIS_QUARTER
13  NEXT_QUARTER
14  LAST_90_DAYS
15  NEXT_90_DAYS
16  LAST_FISCAL_QUARTER
17  THIS_FISCAL_QUARTER
18  NEXT_FISCAL_QUARTER
19  LAST_YEAR
20  THIS_YEAR
21  NEXT_YEAR
22  LAST_FISCAL_YEAR
23  THIS_FISCAL_YEAR
24  NEXT_FISCAL_YEAR
25}

Range values for dates capture dates within a period of time. See SOQL and SOSL Reference: Date Formats and Date Literals in WHERE Clauses.

1input DateRange {
2  n_days_ago:             Int
3  n_weeks_ago:            Int
4  n_months_ago:           Int
5  n_quarters_ago:         Int
6  n_years_ago:            Int
7  n_fiscal_quarters_ago:  Int
8  n_fiscal_years_ago:     Int
9  last_n_days:            Int
10  next_n_days:            Int
11  last_n_weeks:           Int
12  next_n_weeks:           Int
13  last_n_months:          Int
14  next_n_months:          Int
15  last_n_quarters:        Int
16  next_n_quarters:        Int
17  last_n_years:           Int
18  next_n_years:           Int
19  last_n_fiscal_quarters: Int
20  next_n_fiscal_quarters: Int
21  last_n_fiscal_years:    Int
22  next_n_fiscal_years:    Int
23}

Date functions help you convert date values to the default time zone. See SOQL and SOSL Reference: Converting Time Zones in Date Functions.

1input DateFunctionInput {
2  value:                LongOperators # a value in UTC
3  convertTimezoneValue: LongOperators # convert the value to the default time zone
4}

DateTime Fields

DateTime fields map to the DateTimeOperators filter type.

1input DateTimeOperators {
2  eq:  DateTimeInput
3  ne:  DateTimeInput
4  lt:  DateTimeInput
5  gt:  DateTimeInput
6  lte: DateTimeInput
7  gte: DateTimeInput
8  in:  [DateTimeInput]
9  nin: [DateTimeInput]
10  CALENDAR_MONTH:   DateFunctionInput
11  CALENDAR_QUARTER: DateFunctionInput
12  CALENDAR_YEAR:    DateFunctionInput
13  DAY_IN_MONTH:     DateFunctionInput
14  DAY_IN_WEEK:      DateFunctionInput
15  DAY_IN_YEAR:      DateFunctionInput
16  FISCAL_MONTH:     DateFunctionInput
17  FISCAL_QUARTER:   DateFunctionInput
18  FISCAL_YEAR:      DateFunctionInput
19  WEEK_IN_MONTH:    DateFunctionInput
20  WEEK_IN_YEAR:     DateFunctionInput
21  DAY_ONLY:         DateTimeFunctionInput
22  HOUR_IN_DAY:      DateFunctionInput
23}

DateTime fields map to the DateTimeInput filter type.

1input DateTimeInput {
2  value:   DateTime     # An exact DateTime value
3  literal: DATE_LITERAL # a literal value for a relative time
4  range:   DateRange    # a range of Dates
5}

DateTime functions help you convert date time values to the default time zone. See SOQL and SOSL Reference: Converting Time Zones in Date Functions.

1input DateTimeFunctionInput {
2  value:                DateTimePrimitiveOperators # a value in UTC
3  convertTimezoneValue: DateTimePrimitiveOperators # convert the value to the default time zone
4}

DateTime primitive operators allow working with DateTime values directly.

1input DateTimePrimitiveOperators {
2  eq:  DateTime
3  ne:  DateTime
4  lt:  DateTime
5  gt:  DateTime
6  lte: DateTime
7  gte: DateTime
8  in:  [DateTime]
9  nin: [DateTime]
10}

Time Fields

Time fields map to the TimeOperators filter type.

1input TimeOperators {
2  eq:  Time
3  ne:  Time
4  lt:  Time
5  gt:  Time
6  lte: Time
7  gte: Time
8  in:  [Time]
9  nin: [Time]
10}

Boolean Field Type

Boolean fields map to the BooleanOperators filter type.

1input BooleanOperators {
2  eq: Boolean
3  ne: Boolean
4}

ID Field Type

ID fields map to the IdOperators filter type.

1input IdOperators {
2  eq:  ID
3  ne:  ID
4  lt:  ID
5  gt:  ID
6  lte: ID
7  gte: ID
8  in:  [ID]
9  nin: [ID]
10  inq: JoinInput
11  ninq: JoinInput
12}

Either the 15-character and 18-character ID values is accepted. For example. Account( where: { Id: { eq: "0011a000005slme" } } ) returns the same result as Account( where: { Id: { eq: "0011a000005slmeAAA" } } ).

The inq and ninq operators (in-query and not-in-query) are of the JoinInput type. Use these operators to execute semi-join and anti-join queries.

Picklist Field Type

Picklist fields map to the PicklistOperators filter type.

1input PicklistOperators {
2  eq:   Picklist
3  gt:   Picklist
4  gte:  Picklist
5  in:   [Picklist]
6  like: Picklist
7  lt:   Picklist
8  lte:  Picklist
9  ne:   Picklist
10  nin:  [Picklist]
11}

Multi-Picklist Field Type

Multi-picklist fields map to the MultiPicklistOperators filter type.

1input MultiPicklistOperators {
2  eq:       MultiPicklist
3  ne:       MultiPicklist
4  includes: [MultiPicklist]
5  excludes: [MultiPicklist]
6}

Latitude Field Type

Latitude fields map to the LatitudeOperators filter type.

1input LatitudeOperators {
2  eq: Latitude
3  ne: Latitude
4  lt: Latitude
5  gt: Latitude
6  lte: Latitude
7  gte: Latitude
8  in: [Latitude]
9  nin: [Latitude]
10}

Longitude Field Type

Longitude fields map to the LongitudeOperators filter type.

1input LongitudeOperators {
2  eq: Longitude
3  ne: Longitude
4  lt: Longitude
5  gt: Longitude
6  lte: Longitude
7  gte: Longitude
8  in: [Longitude]
9  nin: [Longitude]
10}

Geolocation Field Types

A compound field of type Geolocation maps to the GeolocationOperators filter type.

1GeolocationOperators {
2    lt: GeolocationInput
3    gt: GeolocationInput
4}

For GeolocationOperators, the lt and gt operators are of the GeolocationInput type.

1GeolocationInput {
2  latitude: Latitude!
3  longitude: Longitude!
4  radius: Float!
5  unit: Unit! # MI or KM
6}

Use the geolocation operators to run location-based queries.

Example Arguments

Here are a few sample arguments to demonstrate how to filter on a field.

1where: { Id: { eq: "001xx000003GYQxAAO" } }

1where: { Id: { in: [ "001xx000003GYQxAAO", "001xx000003GYQxAA1" ] } }

1where: { NextStep: { ne: null } }

1where: { Name: {like: "%erv" } }

1where: { SchedStartTime: { gte: { range: { last_n_months: 4 } } } }

1where: { CreatedDate: { lte: { range: { n_days_ago: 2 } } } }

1where: { CreatedDate: { eq: { literal: TODAY } } }

1where: { CreatedDate : { CALENDAR_YEAR: { value: { eq: 2022 } } } }

1where: { LastModifiedDate: { gte: { value: "2022-06-12T03:29:56.901Z"} } }

This example uses multiple operations on a single operator type. The two conditions are AND’d together.

1where: { AnnualRevenue: { gt: 10000, lt: 100000 } }

Example Queries

This example finds opportunities whose NextStep equals “Need estimate”.

1query opportunitiesClosingSoon {
2  uiapi {
3    query {
4      Opportunity(
5        where: {
6          NextStep: { eq: "Need estimate" }
7        }
8      ) {
9        edges {
10          node {
11            Id
12            NextStep {
13              value
14            }
15            CloseDate {
16              value
17              displayValue
18            }
19          }
20        }
21      }
22    }
23  }
24}

This example queries accounts whose names match a given string.

1query accountsWithFilter($where: Account_Filter = {Name: {like: "Burlington%"}}) {
2  uiapi {
3    query {
4      Account(where: $where) {
5        edges {
6          node {
7            Id
8            Name {
9              value
10            }
11          }
12        }
13      }
14    }
15  }
16}

This example finds accounts with an annual revenue of more than 1 million.

1query AccountsGTE1M {
2  uiapi {
3    query {
4      Account(
5        where: {
6          AnnualRevenue: { gte: 1000000 }
7        }
8      ) {
9        edges {
10          node {
11            Id
12            Name {
13              value
14            }
15          }
16        }
17      }
18    }
19  }
20}