Skip to content

Migrating from the XDR Query API

What this covers

Adapt an integration that uses the XDR Query API for historical Data Lake searches. The Search GraphQL API uses QL and a different result format. The XDR Query API remains available.

Prerequisites

Complete the Search quickstart with your tenant credentials. Identify the queries, fields, and downstream consumers your integration needs.

Workflow

Rewrite and compare queries

Use the SQL-to-QL migration guide for translations and compatibility gaps. Use the QL reference for syntax.

Check each query before you switch its workflow:

  • Verify schema and field names. SQL tables do not establish a direct mapping to QL schemas.
  • Set explicit earliest and latest bounds so both searches cover the same time range.
  • Compare string matching, case sensitivity, and regular expressions.
  • Review joins and derived columns. QL does not support SQL joins.
  • Compare representative records and required fields, not only row counts.

Use Data Lake Search to check queries interactively. Use the API reference for the GraphQL contract.

Replace REST requests

Aspect XDR Query API Search GraphQL API
Requests POST to start a run, then GET for status and results JSON POST requests with a GraphQL operation and variables
Query text SQL in adHocQuery.template QL in CreateSearchInput.text
Identifier Query run ID data.createSearch.urn
Completion status: finished and result: succeeded status: COMPLETE, then check outcome
Results items and metadata.columns data.searchResults.values and fields
Pagination page or pageFromKey Pass nextCursor as cursor

Keep the returned search URN for status checks and all result pages. A partition URN identifies one job within a search. An event resource RN identifies an event.

Use the quickstart requests for the create, status, and results sequence.

Update result consumers

Parse values as JSON row objects. Use fields for metadata and types, and handle null or absent values. Follow every returned cursor.

limit bounds rows per page, not the whole search. Optional totals counts the result set, not the current page.

If you add QL projection, check enrichment too. hostname and enrichSummary cannot appear directly in | fields. Removing their input fields can affect their output.

For projection examples and parsing guidance, see Work with search results.

Error handling

Check HTTP status, top-level GraphQL errors, and search outcomes separately. HTTP 200 does not establish success. COMPLETE means execution ended, including when some partitions failed.

Define a policy for PARTIAL results before you switch. Add bounded polling and retries for reads. Avoid blindly repeating a creation request after a timeout.

For diagnostics and retry guidance, see Handle search failures.

Constraints and considerations

Search results expire. Retrieve or store the data you need before search.expireTime. Do not treat a stored URN or cursor as permanent access to the result set.

Before switching, verify the complete workflow with your tenant credentials. Check all pages, required fields, enrichment, and failure handling against your integration's needs.