Field Operators

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.

type Account {
  Name: StringValue
}

input Account_Filter {
  Name: StringOperators
}

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.

tip: 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.

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.

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.

input StringOperators {
  eq:   String
  ne:   String
  like: String
  lt:   String
  gt:   String
  lte:  String
  gte:  String
  in:   [String]
  nin:  [String]
}

Email Fields

Email fields map to the EmailOperators filter type.

input EmailOperators {
  eq: Email
  ne: Email
  like: Email
  lt: Email
  gt: Email
  lte: Email
  gte: Email
  in: [Email]
  nin: [Email]
}

PhoneNumber Fields

PhoneNumber fields map to the PhoneNumberOperators filter type.

input PhoneNumberOperators {
  eq: PhoneNumber
  ne: PhoneNumber
  like: PhoneNumber
  lt: PhoneNumber
  gt: PhoneNumber
  lte: PhoneNumber
  gte: PhoneNumber
  in: [PhoneNumber]
  nin: [PhoneNumber]
}

TextArea Fields

TextArea fields map to the TextAreaOperators filter type.

input TextAreaOperators {
  eq: TextArea
  ne: TextArea
  like: TextArea
  lt: TextArea
  gt: TextArea
  lte: TextArea
  gte: TextArea
  in: [TextArea]
  nin: [TextArea]
}

LongTextArea Fields

LongTextArea fields map to the LongTextAreaOperators filter type.

input LongTextAreaOperators {
  eq: LongTextArea
  ne: LongTextArea
  like: LongTextArea
  lt: LongTextArea
  gt: LongTextArea
  lte: LongTextArea
  gte: LongTextArea
  in: [LongTextArea]
  nin: [LongTextArea]
}

Url Fields

Url fields map to the URLOperators filter type.

input URLOperators {
  eq: Url
  ne: Url
  like: Url
  lt: Url
  gt: Url
  lte: Url
  gte: Url
  in: Url
  nin: Url
}

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.

input DoubleOperators {
  eq:  Double
  ne:  Double
  lt:  Double
  gt:  Double
  lte: Double
  gte: Double
  in:  [Double]
  nin: [Double]
}

Int Fields

Int fields map to the IntegerOperators filter type.

input IntegerOperators {
  eq:  Int
  ne:  Int
  lt:  Int
  gt:  Int
  lte: Int
  gte: Int
  in:  [Int]
  nin: [Int]
}

Long Fields

Long fields map to the LongOperators filter type.

input LongOperators {
  eq: Long
  ne: Long
  lt: Long
  gt: Long
  lte: Long
  gte: Long
  in: [Long]
  nin: [Long]
}

Currency Fields

Currency fields map to the CurrencyOperators filter type.

input CurrencyOperators {
  eq: Currency
  ne: Currency
  lt: Currency
  gt: Currency
  lte: Currency
  gte: Currency
  in: [Currency]
  nin: [Currency]
}

Percent Fields

Percent fields map to the PercentOperators filter type.

input PercentOperators {
  eq: Percent
  ne: Percent
  lt: Percent
  gt: Percent
  lte: Percent
  gte: Percent
  in: [Percent]
  nin: [Percent]
}

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.

input DateOperators {
  eq:  DateInput
  ne:  DateInput
  lt:  DateInput
  gt:  DateInput
  lte: DateInput
  gte: DateInput
  in:  [DateInput]
  nin: [DateInput]
  CALENDAR_MONTH:   DateFunctionInput
  CALENDAR_QUARTER: DateFunctionInput
  CALENDAR_YEAR:    DateFunctionInput
  DAY_IN_MONTH:     DateFunctionInput
  DAY_IN_WEEK:      DateFunctionInput
  DAY_IN_YEAR:      DateFunctionInput
  FISCAL_MONTH:     DateFunctionInput
  FISCAL_QUARTER:   DateFunctionInput
  FISCAL_YEAR:      DateFunctionInput
  WEEK_IN_MONTH:    DateFunctionInput
  WEEK_IN_YEAR:     DateFunctionInput
}

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

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

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.

enum DATE_LITERAL {
  YESTERDAY
  TODAY
  TOMORROW
  LAST_WEEK
  THIS_WEEK
  NEXT_WEEK
  LAST_MONTH
  THIS_MONTH
  NEXT_MONTH
  LAST_QUARTER
  THIS_QUARTER
  NEXT_QUARTER
  LAST_90_DAYS
  NEXT_90_DAYS
  LAST_FISCAL_QUARTER
  THIS_FISCAL_QUARTER
  NEXT_FISCAL_QUARTER
  LAST_YEAR
  THIS_YEAR
  NEXT_YEAR
  LAST_FISCAL_YEAR
  THIS_FISCAL_YEAR
  NEXT_FISCAL_YEAR
}

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

input DateRange {
  n_days_ago:             Int
  n_weeks_ago:            Int
  n_months_ago:           Int
  n_quarters_ago:         Int
  n_years_ago:            Int
  n_fiscal_quarters_ago:  Int
  n_fiscal_years_ago:     Int
  last_n_days:            Int
  next_n_days:            Int
  last_n_weeks:           Int
  next_n_weeks:           Int
  last_n_months:          Int
  next_n_months:          Int
  last_n_quarters:        Int
  next_n_quarters:        Int
  last_n_years:           Int
  next_n_years:           Int
  last_n_fiscal_quarters: Int
  next_n_fiscal_quarters: Int
  last_n_fiscal_years:    Int
  next_n_fiscal_years:    Int
}

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

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

DateTime Fields

DateTime fields map to the DateTimeOperators filter type.

input DateTimeOperators {
  eq:  DateTimeInput
  ne:  DateTimeInput
  lt:  DateTimeInput
  gt:  DateTimeInput
  lte: DateTimeInput
  gte: DateTimeInput
  in:  [DateTimeInput]
  nin: [DateTimeInput]
  CALENDAR_MONTH:   DateFunctionInput
  CALENDAR_QUARTER: DateFunctionInput
  CALENDAR_YEAR:    DateFunctionInput
  DAY_IN_MONTH:     DateFunctionInput
  DAY_IN_WEEK:      DateFunctionInput
  DAY_IN_YEAR:      DateFunctionInput
  FISCAL_MONTH:     DateFunctionInput
  FISCAL_QUARTER:   DateFunctionInput
  FISCAL_YEAR:      DateFunctionInput
  WEEK_IN_MONTH:    DateFunctionInput
  WEEK_IN_YEAR:     DateFunctionInput
  DAY_ONLY:         DateTimeFunctionInput
  HOUR_IN_DAY:      DateFunctionInput
}

DateTime fields map to the DateTimeInput filter type.

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

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

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

DateTime primitive operators allow working with DateTime values directly.

input DateTimePrimitiveOperators {
  eq:  DateTime
  ne:  DateTime
  lt:  DateTime
  gt:  DateTime
  lte: DateTime
  gte: DateTime
  in:  [DateTime]
  nin: [DateTime]
}

Time Fields

Time fields map to the TimeOperators filter type.

input TimeOperators {
  eq:  Time
  ne:  Time
  lt:  Time
  gt:  Time
  lte: Time
  gte: Time
  in:  [Time]
  nin: [Time]
}

Boolean Field Type

Boolean fields map to the BooleanOperators filter type.

input BooleanOperators {
  eq: Boolean
  ne: Boolean
}

ID Field Type

ID fields map to the IdOperators filter type.

input IdOperators {
  eq:  ID
  ne:  ID
  lt:  ID
  gt:  ID
  lte: ID
  gte: ID
  in:  [ID]
  nin: [ID]
  inq: JoinInput
  ninq: JoinInput
}

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.

input PicklistOperators {
  eq:   Picklist
  gt:   Picklist
  gte:  Picklist
  in:   [Picklist]
  like: Picklist
  lt:   Picklist
  lte:  Picklist
  ne:   Picklist
  nin:  [Picklist]
}

Multi-Picklist Field Type

Multi-picklist fields map to the MultiPicklistOperators filter type.

input MultiPicklistOperators {
  eq:       MultiPicklist
  ne:       MultiPicklist
  includes: [MultiPicklist]
  excludes: [MultiPicklist]
}

Latitude Field Type

Latitude fields map to the LatitudeOperators filter type.

input LatitudeOperators {
  eq: Latitude
  ne: Latitude
  lt: Latitude
  gt: Latitude
  lte: Latitude
  gte: Latitude
  in: [Latitude]
  nin: [Latitude]
}

Longitude Field Type

Longitude fields map to the LongitudeOperators filter type.

input LongitudeOperators {
  eq: Longitude
  ne: Longitude
  lt: Longitude
  gt: Longitude
  lte: Longitude
  gte: Longitude
  in: [Longitude]
  nin: [Longitude]
}

Geolocation Field Types

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

GeolocationOperators {
    lt: GeolocationInput
    gt: GeolocationInput
}

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

GeolocationInput {
  latitude: Latitude!
  longitude: Longitude!
  radius: Float!
  unit: Unit! # MI or KM
}

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.

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

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

where: { NextStep: { ne: null } }

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

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

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

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

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

where: { 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.

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

Example Queries

This example finds opportunities whose NextStep equals "Need estimate".

query opportunitiesClosingSoon {
  uiapi {
    query {
      Opportunity(
        where: {
          NextStep: { eq: "Need estimate" }
        }
      ) {
        edges {
          node {
            Id
            NextStep {
              value
            }
            CloseDate {
              value
              displayValue
            }
          }
        }
      }
    }
  }
}

This example queries accounts whose names match a given string.

query accountsWithFilter($where: Account_Filter = {Name: {like: "Burlington%"}}) {
  uiapi {
    query {
      Account(where: $where) {
        edges {
          node {
            Id
            Name {
              value
            }
          }
        }
      }
    }
  }
}

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

query AccountsGTE1M {
  uiapi {
    query {
      Account(
        where: {
          AnnualRevenue: { gte: 1000000 }
        }
      ) {
        edges {
          node {
            Id
            Name {
              value
            }
          }
        }
      }
    }
  }
}