Build a query

Compose a ServiceNow encoded query from typed conditions and use it to filter a table request.

note

Condition values are written into the encoded query verbatim, and ServiceNow's encoded-query syntax has no way to escape its structural characters. Which characters are rejected depends on where the value lands:

• ^ separates clauses — rejected in every value and fragment
• , separates list values — rejected in IsOneOf / IsNotOneOf values only
• @ separates pair halves — rejected in Between values only

Elsewhere , and @ are ordinary literal characters, so values like "Smith, John" or "user@example.com" pass through unchanged. A value containing a rejected character — for example, text taken from user input — could otherwise break out of its term and append arbitrary clauses, so the builder rejects it at construction time instead.

Always check Error() on the finished condition before serializing or sending it:

q := query.And(
    query.Boolean("active").Is(true),
    query.String("name").Is(userInput), // rejected if userInput contains ^
)
if err := q.Error(); err != nil {
    // The value was rejected — do not serialize or send this condition.
    return err
}
sysparmQuery := q.String()

A condition that reports an error has no valid encoded-query form. If you serialize one anyway, String() renders <invalid query> in place of the rejected part — an intentionally unusable term, never a silently weakened query. Date-time composite fragments (Javascript(), JS(), and OnSpecialty()) reject ^ and @, since the package inserts those separators itself; commas are allowed there, e.g. multi-argument gs.* calls.

When to use this pattern

• You're filtering records with more than one or two conditions, or building queries from runtime values
• You want the compiler to catch operator/type mismatches instead of discovering a malformed encoded query at runtime
• For a short, static filter, passing the encoded-query string directly (as in List and query records) is fine — the builder earns its keep when composing conditions by hand gets error-prone

Required values

Value	Description
Table name	The table to filter (for example, incident)
Conditions	The fields, operators, and values to filter by

Example

package main

import (
	"context"
	"fmt"
	"log"

	servicenow "github.com/michaeldcanady/servicenow-sdk-go/v2"
	"github.com/michaeldcanady/servicenow-sdk-go/v2/credentials"
	"github.com/michaeldcanady/servicenow-sdk-go/v2/query"
	tableapi "github.com/michaeldcanady/servicenow-sdk-go/v2/tableapi"
)

func main() {
  // Step 1: Authenticate and initialize the client
  cred := credentials.NewBasicProvider("{username}", "{password}")

  client, err := servicenow.NewServiceNowServiceClient(
  	servicenow.WithAuthenticationProvider(cred),
  	servicenow.WithInstance("{instance}"),
  )
  if err != nil {
  	log.Fatalf("failed to initialize client: %v", err)
  }

  // Step 2: Compose the query from typed conditions
  q := query.Boolean("active").Is(true).
  	And(query.String("priority").IsOneOf("1", "2")).
  	String() // renders the encoded query: active=true^priorityIN1,2

  // Step 3: Use it in the request configuration
  config := &tableapi.TableRequestBuilderGetRequestConfiguration{
  	QueryParameters: &tableapi.TableRequestBuilderGetQueryParameters{
  		Query: &q,
  	},
  }

  response, err := client.Now().Table("{TableName}").Get(context.Background(), config)
  if err != nil {
  	log.Fatalf("unable to list records: %v", err)
  }

  records, err := response.GetResult()
  if err != nil {
  	log.Fatal(err)
  }

  fmt.Printf("Matched %d records\n", len(records))
}

Variations

Inspect the encoded query

String() renders the condition tree into ServiceNow's encoded-query syntax — print it to see exactly what will be sent:

q := query.String("short_description").Contains("System").
	And(query.Number("priority").Is(1)).String()

fmt.Println(q) // Output: short_descriptionLIKESystem^priority=1

Plug the query into a table request

Pass the rendered string as the Query query parameter of a list request:

// Build the query
q2 := query.Boolean("active").Is(true).
	And(query.String("priority").
		IsOneOf("1", "2")).String()

params := &tableapi.TableRequestBuilderGetQueryParameters{
	Query: &q2,
}

config := &tableapi.TableRequestBuilderGetRequestConfiguration{
	QueryParameters: params,
}

response, err := client.Now().Table("{TableName}").Get(ctx, config)
if err != nil {
	log.Fatal(err)
}

Field types and operators

Conditions start from a typed field constructor — query.String, query.Number, query.Boolean, query.Date/query.DateTime — each exposing the operators valid for that type (Is, Contains, IsOneOf, Before, …). Combine conditions with .And(...)/.Or(...) or the top-level query.And(...)/query.Or(...).

Tips

• Encoded-query cheat sheet: ^ joins with AND, ^OR with OR, LIKE matches substrings — the builder emits these for you.
• The same encoded string works anywhere a sysparm_query is accepted (for example, filtering attachments).

Next steps

• List and query records: The request this query plugs into.
• Iterate over every record: Page through large match sets.