--- schema_version: "1" id: 87e23679546a0e13d2579f2467e54b7c5f8234dacb35e972d49d97d6ee9cf225 title: Field Operators collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/graphql-api/graphql/guides/filter/filter-fields.md canonical_url: https://developer.salesforce.com/docs/platform/graphql/guide/filter-fields.html source_site: developer.salesforce.com content_type: documentation content_hash: d08843b5d3049f7989b15d26ee54d9304bb6180c1fd0c8b6b0157256233063be products: - GraphQL API --- # 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`. ``` 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](https://developer.salesforce.com/docs/platform/graphql/guide/filter-boolean.md) 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](https://developer.salesforce.com/docs/platform/graphql/guide/filter-joins.md). | | `ninq` | Is not an element in query. Use this function to create an [anti-join filter](https://developer.salesforce.com/docs/platform/graphql/guide/filter-joins.md). | Fields on sObjects have corresponding mappings to `Operators` types. The main field types are: - [String Field Types](#string-field-types) - String - Email - PhoneNumber - TextArea - LongTextArea - Url - [Number Field Types](#number-field-types) - Double - Int - Long - Currency - Percent - [Date and Time Field Types](#date-datetime-and-time-field-types) - Date - DateTime - Time - [Other Types](#boolean-field-type) - 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](https://developer.salesforce.com/docs/atlas.en-us.soql_sosl.meta/soql_sosl/sforce_api_calls_sosl_where.htm). ### 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](https://developer.salesforce.com/docs/atlas.en-us.soql_sosl.meta/soql_sosl/sforce_api_calls_soql_select_dateformats.htm). ``` 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](https://developer.salesforce.com/docs/atlas.en-us.soql_sosl.meta/soql_sosl/sforce_api_calls_soql_select_dateformats.htm). ``` 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](https://developer.salesforce.com/docs/atlas.en-us.soql_sosl.meta/soql_sosl/sforce_api_calls_soql_select_convert_time_zone.htm). ``` 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](https://developer.salesforce.com/docs/atlas.en-us.soql_sosl.meta/soql_sosl/sforce_api_calls_soql_select_convert_time_zone.htm). ``` 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](https://developer.salesforce.com/docs/platform/graphql/guide/filter-joins.md). ## 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](https://developer.salesforce.com/docs/platform/graphql/guide/filter-location.md). ## 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 } } } } } } } ```