EXPLAIN Commands

The star of the FSQL show is the QUERY command. But FSQL has a supporting cast of other commands. The EXPLAIN commands

Note: if you're using FSQL through Query's search UI, you only have access to the QUERY command today. API and console users have access to the full set of commands shown here.

EXPLAIN VERSION

FSQL is new technology and advancing quickly. The EXPLAIN VERSION command can retrieve the FSQL and Query Data Model versions of the FSQL server you're working with.

EXPLAIN VERSION

Response:

{
	"fsql": "fsql-0.5.0",
	"qdm": "qdm-1.4.1+ocsf-1.4.0"
}

EXPLAIN ATTRIBUTES

FSQL owes a lot of its power to its attribute selectors. If you'd like to test an attribute selector, you can see what one evaluates to with the EXPLAIN ATTRIBUTES command.

For example, if you want to see all fields of network_activity that are IP observables, try the following:

EXPLAIN ATTRIBUTES network_activity.%ip

Response:

[
	"network_activity.device.ip",
	"network_activity.device.network_interfaces.ip",
	"network_activity.dst_endpoint.intermediate_ips",
	"network_activity.dst_endpoint.ip",
	"network_activity.dst_endpoint.ip_intelligence.ip",
	"network_activity.dst_endpoint.proxy_endpoint.intermediate_ips",
	"network_activity.dst_endpoint.proxy_endpoint.ip",
	"network_activity.load_balancer.dst_endpoint.intermediate_ips",
	"network_activity.load_balancer.dst_endpoint.ip",
	"network_activity.load_balancer.ip",
	"network_activity.osint.email.x_originating_ip",
	"network_activity.proxy.intermediate_ips",
	"network_activity.proxy.ip",
	"network_activity.proxy.ip_intelligence.ip",
	"network_activity.proxy_endpoint.intermediate_ips",
	"network_activity.proxy_endpoint.ip",
	"network_activity.proxy_endpoint.ip_intelligence.ip",
	"network_activity.proxy_http_request.x_forwarded_for",
	"network_activity.src_endpoint.intermediate_ips",
	"network_activity.src_endpoint.ip",
	"network_activity.src_endpoint.ip_intelligence.ip",
	"network_activity.src_endpoint.proxy_endpoint.intermediate_ips",
	"network_activity.src_endpoint.proxy_endpoint.ip"
]

EXPLAIN SCHEMA

The EXPLAIN SCHEMA command describes the schema for a given attribute selection. It expands the attribute selector expression and responds with the schema definition for each path that's been selected. If you're familiar with OCSF schema definitions, you should feel right at home with the output.

EXPLAIN SCHEMA network_activity.proxy.%ip

Response:

{
	"network_activity.proxy.intermediate_ips": {
		"caption": "Intermediate IP Addresses",
		"type": "ip_t",
		"requirement": "optional",
		"description": "The intermediate IP Addresses. For example, the IP addresses in the HTTP X-Forwarded-For header.",
		"is_array": true,
		"observable": 2
	},
	"network_activity.proxy.ip": {
		"caption": "IP Address",
		"type": "ip_t",
		"requirement": "recommended",
		"description": "The IP address of the endpoint, in either IPv4 or IPv6 format.",
		"is_array": false,
		"observable": 2
	},
	"network_activity.proxy.ip_intelligence.ip": {
		"caption": "IP Address",
		"type": "ip_t",
		"requirement": "optional",
		"description": "The IP address, in either IPv4 or IPv6 format.",
		"is_array": false,
		"observable": 2
	}
}

By default, FSQL removes keys from the response with null values. You can enable them by adding WITH NULLS after the attribute selector (WITHOUT NULLS has the opposite effect). For example:

EXPLAIN SCHEMA network_activity.proxy.ip WITH NULLS

Response:

{
	"network_activity.proxy.ip": {
		"caption": "IP Address",
		"type": "ip_t",
		"requirement": "recommended",
		"description": "The IP address of the endpoint, in either IPv4 or IPv6 format.",
		"is_array": false,
		"@deprecated": null,
		"enum": null,
		"group": null,
		"observable": 2,
		"profile": null,
		"sibling": null,
		"object_type": null,
		"object_name": null,
		"type_name": null
	}
}

EXPLAIN CONNECTORS

The EXPLAIN CONNECTORS command lists all connectors available to your FSQL session.

The output includes the connector ID, connector name, whether or not the connector is enabled, and the name of the source platform.

EXPLAIN CONNECTORS

Response:

[
	{
		"id": 1389,
		"name": "SL-CTM-AcctChg",
		"is_enabled": true,
		"platform_name": "AwsSecurityLake"
	},
	{
		"id": 1192,
		"name": "WHOIS",
		"is_enabled": true,
		"platform_name": "Whois"
	},
	{
		"id": 1193,
		"name": "AV",
		"is_enabled": true,
		"platform_name": "AlienVault"
	},
	{
		"id": 1199,
		"name": "Virus Total",
		"is_enabled": true,
		"platform_name": "VirusTotal"
	},
	{
		"id": 1142,
		"name": "ATB - Intune",
		"is_enabled": true,
		"platform_name": "MicrosoftIntune"
	},
	{
		"id": 1370,
		"name": "SecOps AWS ALB",
		"is_enabled": true,
		"platform_name": "GoogleSecOps"
	},
	{
		"id": 1233,
		"name": "Lancet3 DLP Findings",
		"is_enabled": true,
		"platform_name": "AzureLogAnalytics"
	}
]

EXPLAIN MANUAL

The EXPLAIN MANUAL command responds with this documentation in Markdown format.

EXPLAIN GRAPHQL

If you're familiar with Query's GraphQL search API, you can use the EXPLAIN GRAPHQL command to translate an FSQL query into a GraphQL request. The example below shows a translated search query, but the EXPLAIN GRAPHQL command also provides a subscription query that can be used to retrieve results for a submitted search query.

EXPLAIN GRAPHQL QUERY network_activity.* WITH network_activity.count < 50 BEFORE 1h AFTER 720h

Response:

query {
  search {
    id
    status
    data {
      network_activity(
        filter: {
          op: AND
          conditions: [
            {
              fields: {
                time: {
                  greater_than_equals: "2025-03-29T14:49:02.884049"
                  less_than_equals: "2025-04-28T13:49:02.883945"
                }
              }
            }
            { op: OR, conditions: [{ fields: { count: { less_than: 50 } } }] }
          ]
        }
      ) {
        connection_id
        action_id
        activity_id
        app_name
        category_uid
        class_uid
        confidence_id
        confidence_score
        count
        disposition_id
        duration
        end_time
        is_alert
        message
        record_id
        risk_details
        risk_level_id
        risk_score
        severity_id
        start_time
        status_code
        status_detail
        status_id
        time
        timezone_offset
        type_uid
      }
    }
  }
}