Build a query

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

note

This is a preview feature currently under active development.

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.