Skip to main content
Version: 4.8.0

Querying the Instance

now-sdk query runs a read-only Table REST API query against the authenticated ServiceNow instance. Use it for live, instance-specific data — column metadata, existing sys_ids, choice values, role memberships, scope info, etc.

now-sdk query <table> --query '<encoded_query>' [options]

Options​

Required​

  • <table> — table name (e.g., incident, sys_dictionary)
  • --query, -q — encoded query string, e.g. active=true^priority<=2

Paging​

  • --limit (default 100) — page size
  • --offset (default 0) — starting offset

Field shaping​

  • --fields, -f — comma-separated field list (dramatically reduces response size)
  • --display-value — true | false | all (default false)
  • --exclude-reference-link (default true) — omit Table API links for reference fields
  • --no-count — skip X-Total-Count header (faster on big tables)
  • --view — UI view for field selection

Other​

  • --output, -o — output format: json for machine-readable envelope
  • --auth, -a — credential alias (omit for default)
  • --timeout (default 30000) — per-request timeout in ms
  • --query-category — category for extended queries (advanced)
  • --query-no-domain — ignore domain separation (advanced)

Output (-o json)​

Success:

{"ok": true, "hasMore": false, "nextOffset": null, "records": [...]}
  • hasMore — true if more records exist
  • nextOffset — offset for the next page when hasMore is true

Error:

{"ok": false, "error": {"message": "Table API request failed: 404 Not Found", "status": 404, "table": "bogus_table"}}
  • message — error description
  • status — HTTP status code (when available)
  • table — the table that was queried

Check ok before consuming records.

Pagination​

Use hasMore and nextOffset to page through large result sets:

# First page
now-sdk query incident -q 'active=true' -f 'number' --limit 100 -o json
# {"ok":true,"hasMore":true,"nextOffset":100,"records":[...]}

# Next page
now-sdk query incident -q 'active=true' -f 'number' --limit 100 --offset 100 -o json
# {"ok":true,"hasMore":false,"nextOffset":null,"records":[...]}

Loop until hasMore is false or null.

Recipes​

# Table columns
now-sdk query sys_dictionary \
  -q 'name=incident^elementISNOTEMPTY' \
  -f 'element,column_label,internal_type,reference,mandatory' -o json

# Table inheritance
now-sdk query sys_db_object -q 'name=incident' \
  -f 'name,super_class,label' --display-value all -o json

# Resolve name → sys_id
now-sdk query sys_user_role -q 'name=admin' -f 'sys_id,name' -o json
now-sdk query sys_scope -q 'scope=x_acme_app' -f 'sys_id,scope,name' -o json

# Check for collision
now-sdk query sys_script \
  -q 'name=My Rule^collection=incident' -f 'sys_id,name' -o json
# If records.length > 0, record exists

# ACLs on a table
now-sdk query sys_security_acl \
  -q 'name=incident^ORnameSTARTSWITHincident.' \
  -f 'sys_id,name,operation,active' -o json

# Large result set (paginate using hasMore/nextOffset)
now-sdk query incident -q 'active=true' --limit 500 \
  -f 'number,short_description' -o json

Tips​

  • Always pass --fields — bare queries return every column
  • Use ^ for AND, ^OR for OR, STARTSWITH/CONTAINS/IN for matching
  • --display-value all gets both raw and display values in one call
  • Read-only — for mutations, use now-sdk install