Search GraphQL API types¶
API under active development
Introspection may show fields or types that this reference does not document. Use this documentation to identify officially supported fields and types.
Every named type reachable from a query or mutation in this schema, grouped by kind.
Jump to: Objects · Enums · Input objects · Scalars
Objects¶
HostnameMapping¶
A hostname in the query and the host identifiers it resolved to.
Fields¶
| Field | Type | Description |
|---|---|---|
hostname | String! | The hostname referenced by the query. |
hostIds | [String!]! | The host IDs resolved from this hostname. One hostname can resolve to multiple host IDs over time. |
SearchOutcome¶
Describes how complete a search was once it finished.
Fields¶
| Field | Type | Description |
|---|---|---|
success | PartitionsSuccess! | How many of the search's partitions succeeded. Is UNKNOWN until complete. |
errors | [SearchPartitionError!]! | The accumulated errors from every FAILED or CANCELED partition, as well as warnings and other diagnostic errors associated with them. |
SearchPartition¶
The actionable job or jobs associated with a search. Each search request is handled by one or more search jobs aligning to output schemas they generate, and these "partitions" of the search may be separately tracked, referenced or read.
Fields¶
| Field | Type | Description |
|---|---|---|
urn | URN! | The partition identifier. |
searchURN | URN! | The identifier of the search this partition is associated with. |
schemaType | String | The pre-defined schema this partition targets, if any. Unset for partitions whose output schema is generated dynamically from the query (e.g. aggregations). |
status | PartitionStatus! | The current execution status of the partition. |
overThreshold | Boolean! | Whether this partition is predicted to exceed the long-running threshold. |
errors | [String!]! | Errors, warnings or other diagnostic messages generated while attempting to run this search partition job. This may have values even while the status is SUCCEEDED. |
createTime | Time! | The time the partition was created. |
startTime | Time | The time the partition moved to a running state. |
endTime | Time | The time the partition moved to a completed state. |
expireTime | Time! | The time when this partition's results will be discarded. |
SearchPartitionError¶
Errors and warnings associated with one search partition.
Fields¶
| Field | Type | Description |
|---|---|---|
urn | URN! | The URN of the search partition that produced these messages. |
errors | [String!]! | The accumulated error messages for the partition. |
SearchResultField¶
The name and type metadata of a field in the result set.
Fields¶
| Field | Type | Description |
|---|---|---|
name | String! | The fully qualified name of the field, including all parent field names separated by .. For example, source_port or process_file_hash.md5. |
baseType | BaseType! | The base type that applies to the field, or to a list field's items. |
logicalType | LogicalType | A QL logical type that resolves to this field, when one exists. |
enumValues | [String!] | The possible values this field may have. Only for enum fields. |
originSchemaTypes | [String!]! | The pre-defined schema(s) that this field originates from. |
SearchResultPage¶
A page of result rows, field metadata, and optional counts for a search or search partition.
Fields¶
| Field | Type | Description |
|---|---|---|
fields | [SearchResultField!]! | The result set's available fields. |
values | SearchResultValues! | The values of this page of the result set. |
totals | SearchResultTotals | The total result counts for the search or partition. |
nextCursor | String | The page token to use when listing the next page of search results. Not set if this is the last page of the result set. |
previousCursor | String | The page token to use when listing the previous page of search results. Not set if this is the first page of the result set. |
hostnameMappings | [HostnameMapping!] | For hostname queries, the mapping of each hostname named in the query to the host IDs it resolved to during translation. Empty for queries with no hostname filter. |
SearchResultSubTotal¶
The result count for one schema type.
Fields¶
| Field | Type | Description |
|---|---|---|
schemaType | String! | The schema type for this count. |
value | Int64! | The number of result rows for this schema type. |
SearchResultTotal¶
A total number of result rows.
Fields¶
| Field | Type | Description |
|---|---|---|
value | Int64! | The number of result rows. |
SearchResultTotals¶
Total and per-schema result counts.
Fields¶
| Field | Type | Description |
|---|---|---|
total | SearchResultTotal | The total result count, when available. |
subtotals | [SearchResultSubTotal!] | Result counts for this search's partitions, each labeled by schema type. A direct search partition read returns a subtotal for that partition. |
SearchV2 F¶
An execution of a query at a specific time.
Fields¶
| Field | Type | Description |
|---|---|---|
urn | URN! | The search identifier. |
status | SearchExecutionStatus! | The current status of the search, derived from its partitions' statuses. |
overThreshold | Boolean! | Whether any partition is predicted to exceed the long-running threshold. |
errors | [String!]! | Search-scoped diagnostics captured when the request is accepted. Today this only contains non-fatal validation warnings. Execution failures belong to their individual search partitions, available under the outcome field. |
outcome | SearchOutcome! | How completely the search's partitions have succeeded, and errors from any that have failed. If the search itself failed this will have no errors and an UNKNOWN success: see the errors field and status on the search itself for clarity. |
queryText | String! | The query executed by this search, in the QL text format. If the query was submitted as text, this is the original text as provided. If the query was submitted as QuerySpec, this is a generated, canonical representation. |
searchPartitions | [SearchPartition!]! | Search partitions are the actionable search jobs that are spawned from a search request. They map directly to the output schema or schemas that this query generates. |
createTime | Time! | The time the search was created. |
startTime | Time | The time the search moved to a running state. |
endTime | Time | The time the search moved to a completed state. |
expireTime | Time! | The time when this search's results will be discarded or invalid. Aligns with the earliest associated partition's expiry. |
metadata | Map | Arbitrary client-provided metadata attached to the search. While certain metadata keys may be validated by the API, if the search succeeds the metadata is stored and retained without transformation. |
hostnameMappings | [HostnameMapping!] | For queries that include hostname matching, this holds the map of each referenced hostname to its resolved host ids. It will be empty for queries with no hostnames. |
Enums¶
BaseType¶
A data type of a result field, including list and map shapes.
Values¶
| Value | Description |
|---|---|
STRING | A string without a specified structure. |
NUMBER | An integer or decimal number. |
BOOL | A boolean value. |
TIMESTAMP_SECONDS | An integer of the number of seconds since the unix epoch. |
TIMESTAMP_MILLISECONDS | An integer of the number of milliseconds since the unix epoch. |
TIMESTAMP_MICROSECONDS | An integer of the number of microseconds since the unix epoch. |
TIMESTAMP_ISO_8601 | An ISO 8601 compliant string. |
BYTES | A base64 encoded string of byte data. |
ENUM | A string limited to specific values. |
STRING_LIST | A list of strings without specified structure. |
NUMBER_LIST | A list of integer or decimal numbers. |
BOOL_LIST | A list of boolean values. |
TIMESTAMP_SECONDS_LIST | A list of integers of the number of seconds since the unix epoch. |
TIMESTAMP_MILLISECONDS_LIST | A list of integers of the number of milliseconds since the unix epoch. |
TIMESTAMP_MICROSECONDS_LIST | A list of integers of the number of microseconds since the unix epoch. |
TIMESTAMP_ISO_8601_LIST | A list of ISO 8601 compliant strings. |
BYTES_LIST | A list of base64 encoded strings of byte data. |
ENUM_LIST | A list of strings limited to specific values. |
STRING_MAP | A map of strings to strings. |
NUMBER_MAP | A map of strings to decimal or integer numbers. |
BOOL_MAP | A map of strings to boolean values. |
TIMESTAMP_SECONDS_MAP | A map of strings to integers of the number of seconds since the unix epoch. |
TIMESTAMP_MILLISECONDS_MAP | A map of strings to integers of the number of milliseconds since the unix epoch. |
TIMESTAMP_MICROSECONDS_MAP | A map of strings to integers of the number of microseconds since the unix epoch. |
TIMESTAMP_ISO_8601_MAP | A map of strings to ISO 8601 compliant strings. |
BYTES_MAP | A map of strings to base64 encoded strings of byte data. |
ENUM_MAP | A map of strings to strings limited to specific values. |
LogicalType¶
A semantic matcher for fields across schemas in QL. Each value corresponds to an @-prefixed QL reference.
Values¶
| Value | Description |
|---|---|
COMMAND | @command |
HASH | @hash |
DOMAIN | @domain |
HOST | @host |
IP | @ip |
LATITUDE | @latitude |
LONGITUDE | @longitude |
MAC | @mac |
PATH | @path |
PORT | @port |
RAW | @raw |
USER | @user |
URL | @url |
UUID | @uuid |
SENSOR_ID | @sensor_id |
TIMESTAMP | @timestamp |
PartitionStatus¶
The execution state of one search partition.
Values¶
| Value | Description |
|---|---|
WAITING | The search partition has not started. |
IN_PROGRESS | The search partition is running. |
SUCCEEDED | The search partition finished successfully. |
FAILED | The search partition failed. |
CANCELED | The search partition was canceled. |
PartitionsSuccess¶
Relative description of how many partitions succeeded within a search.
Values¶
| Value | Description |
|---|---|
UNKNOWN | The search has not completed. |
ALL | All partitions succeeded. |
PARTIAL | Some partitions succeeded and some did not. |
NONE | No partitions succeeded. |
SearchExecutionStatus¶
The execution status of a search, derived from the statuses of its partitions.
Values¶
| Value | Description |
|---|---|
QUEUED | The search is waiting to start. All partitions are waiting. |
IN_PROGRESS | The search has started, and at least one partition has not finished. |
COMPLETE | All partitions have finished. Check outcome for success or failure. |
Input objects¶
CreateSearchInput¶
The query and optional settings used to start a search.
Fields¶
| Field | Type | Description |
|---|---|---|
text | String | The query to execute in this search, in the QL text format. Exactly one of text or spec must be provided. |
metadata | Map | Arbitrary metadata stored alongside the search. |
Scalars¶
Int64¶
A signed 64-bit integer.
Map¶
A JSON object with string keys and values of any JSON type.
SearchResultValues¶
Raw data returned in a page of results, formatted as a JSON array of objects.
Time¶
A timestamp formatted according to ISO 8601.
URN¶
A Search Platform URN in the format urn:type:visibility:app:tenant:timestamp:uuid. This identifier is distinct from the standard resource name (RNs) used by other APIs as identifiers for core resources.
Federated types and introspection. Types marked with F are federated across one or more APIs in the graph. Other subgraphs may provide more fields than those strictly defined here.