Skip to main content

Query workspace

A query tab in Explorer is where you write and run queries against your connected data sources, your endpoint fleet, or the Huntbase entity graph. Every query tab has the same layout: a query bar along the top, an optional parameter strip below it, and a results pane that fills the rest of the tab.

A query tab with the query bar, a filled parameter strip, and a table of results underneath

Open a query tab​

You can reach a query tab from several places:

FromHow
The ask boxOn Explorer or in a new tab, type or paste a query: Auto-detect recognises it, and the line under the box says what Enter will do. To write one yourself, pick Treat as ▾ › Query (Ctrl+Shift+3).
The header's NewUnder the new navigation, New › Query opens a blank query.
Content library › QueriesOpen a query template and click Open in Query. The template's language and parameters are pre-filled.
A Scout chatOn a query card, click See Results to open that query and its run in a tab. Follow-up query suggestions from Scout also open as query tabs.
Query historyOpen a run and click Open query to reopen the query with that run's results. See Query history.
Deep linkShare or bookmark a query tab's URL. Opening it recreates the tab, including the run if one is referenced.
Explorer's + menuNew query opens a blank query tab. Search telemetry opens one in Search mode. Where new tabs are available, + opens a new tab: pick Query (or let Auto recognise your query), and the ▾ next to it lists New query and Search telemetry.

Queries stay open while you move around Explorer, so a long-running query keeps streaming when you switch to a chat or a hunt.

Rolling out

The new navigation is rolling out and may not be enabled for your organization yet. Under it, Explorer has no tab bar: each query opens by its link, Back returns to where you were, and the open navigation's Recent list holds the queries, hunts and chats you had open. In the classic layout, each query is a tab in Explorer's tab bar.

Search and Query modes​

Beta

This feature is currently rolling out and may not be enabled for your organization.

When searching telemetry is available, a Search / Query toggle sits at the left of the bar. Query is the query editor this page describes. Search searches the telemetry your shippers send, and you filter it by clicking values. Huntbase writes the search as a KQL (Huntbase Lake) query.

Search and Query share one frame: switching changes the input, not the page. Query ▸ shows the search's query in place, and Edit as query (or Query on the toggle) puts it in the editor while the results, Fields and filters stay on screen. The results change only when you Run the edited query. Search on the toggle returns to your filters. See See the query behind a search.

In a new tab, the same search is a language: Search (Huntbase Lake) is first in Query's language pill.

The query bar​

The query bar groups everything the run needs, left to right: which language, which connections, the time window (for some languages), the query itself, and Run.

Query bar with the language pill menu open, showing the connected sources and no connected source groups

Choose a language​

The first pill picks the query language. Click it to open the menu:

LanguageWhat it runs against
AutoDescribe what you're looking for in plain language — Scout translates the prompt into a query.
SQLiteUnified SQL across all connected data sources.
osquerySQLite over your endpoint fleet — endpoints as tables.
CypherGraph query language for entity-relationship analysis.
SPLNative passthrough to Splunk.
KQLNative passthrough to Microsoft Sentinel / ADX.
ES|QLNative passthrough to Elastic (piped syntax).
ES Query DSLNative passthrough to Elastic (Lucene query string).
StormNative passthrough to Vertex Synapse, read-only.
STIXSTIX 2.1 pattern expressions, translated per connection.

The menu is grouped by what your connections can serve: natural language, then connected sources, then no connected source. Languages in the last group are dimmed but still selectable, so you can draft a query before the matching connection exists. When a template is active, the language is locked to the template's language.

See Query languages for syntax and examples.

Choose connections​

The connection pill lists the connections in your current scope that serve the selected language. Auto-select (the default) runs across the ones that can answer; tick one or more connections to run manually against just those. When you run against more than one connection, results are merged into one result set.

Auto-select leaves out connections that can't answer: ones that are Failing, have no key set, or are switched off, and connections that can't run the language natively, such as some simulated ones. The picker says how many it uses, for example Auto-select (4 of 6 in scope), and says which it skips and why. Skipped connections are still listed, marked for example Failing · not auto-selected, so you can still tick one by hand. The pill counts the connections Auto-select will use. When two connections share a name, the picker adds the product and a short id, for example Splunk 1 · Splunk · 2304fe. See Connections › Status.

Some languages need no connection at all, and the pill says which source they read instead: Entity graph for Cypher, or Data lake for KQL (Huntbase Lake), which searches the Huntbase data lake and every lake of yours in federation at once.

When your organization has lakes of its own in federation, KQL (Huntbase Lake) shows a Stores pill in place of Data lake. Run reads the Huntbase data lake and your lakes unless you pick Huntbase Lake only there. The ▾ next to Run also offers Run including your lakes for a single run. The compact bar's summary names the stores the last run read.

Target endpoints (osquery)​

With osquery selected, an extra fleet pill appears. It has two modes:

  • Filter — narrow the fleet by tag, operating system, or hostname pattern. No filters means the whole fleet.
  • Exact — search hostnames and hand-pick specific endpoints.

A live preview at the bottom of the picker shows how many endpoints match.

Open a query targeted at endpoints​

Beta

This feature is currently rolling out and may not be enabled for your organization.

You can also start from the endpoints themselves. In Endpoints, select endpoints and click Run query on these, or click Run query on an endpoint's page. Explorer opens a new query tab with osquery selected and the run limited to exactly those endpoints.

A banner above the editor reads Targeting N endpoints and names them. Watch it before you run:

BannerMeaning
Targeting N endpointsThe run is limited to the endpoints you chose. If you change the picked endpoints, the banner adds "opened for N" so you can see the difference.
"No longer limited to the N endpoints this tab was opened for — the run now follows the fleet filters."The targeting was edited away, so the query would run more widely than you intended. Click Restore targeting to put it back.
"Not limited to the N endpoints this tab was opened for — endpoint targeting only applies to osquery."You switched to another language. Switch back to osquery, or click Restore targeting.

The banner also tells you when some of the endpoints can't be found in the fleet (offline, removed, or not yet enrolled — they stay targeted by ID), or when a fleet they belong to isn't available in your current scope.

If Explorer can't carry the selection over, it warns The endpoint selection didn't carry over and nothing is targeted. Run the query again from Endpoints rather than running the blank tab, which would cover the whole fleet.

Set the time range​

For KQL (Huntbase Lake), SPL, KQL, ES|QL and ES Query DSL, a time-range pill sits next to the editor. Click it to choose a preset or a custom window; the window is sent with the run. Changing only the time range and running again runs over the new window, and reopening an earlier query puts its time range back in the pill. Other languages express time in the query body, so the pill is hidden for them.

An SPL search that sets its own earliest= or latest= keeps those bounds, and the pill reads Time set in query instead of a window the run won't use.

A new query starts on Last 24 hours for KQL (Huntbase Lake), as Search does, and on Last 1 hour for languages that query one of your connected tools, so an untouched query never asks your SIEM for a day of data. Run in new tab carries the time range to the new tab.

Write the query​

The editor highlights syntax for the selected language and offers autocomplete as you type — table and column names for SQL-style languages, keywords for the others, and parameter types after {{name:. Inline markers flag syntax problems before you run.

  • Press Enter to run when the editor is a single line.
  • Open the ⋯ menu at the right of the editor and choose Expand editor for a multi-line editor. In expanded mode, Enter inserts a new line and Cmd/Ctrl+Enter runs. Collapse editor switches back.
  • Show context / Hide context toggles the row of connection and template context above the editor.

Typing in the editor also searches the Content library: matching query templates appear in a dropdown so you can pick one instead of writing from scratch.

Browse the schema​

Choose Schema from the ⋯ menu to open the schema tree. It lists what the selected language can query, grouped as platform › dataset › columns, with a filter box at the top. Expand a platform to load its datasets; click a dataset or column to insert its name into the editor. Use the refresh control to reload the schema.

Use parameters​

Write {{name}} anywhere in a query to make it a parameter. Add a type with {{name:type}} — for example {{days_back:number}} or {{severity:enum[low,medium,high]}}. Names may contain letters, digits, underscores and hyphens.

As soon as the query contains a parameter, a parameter strip appears under the query bar with one field per parameter. Required parameters are marked with *, and Run stays disabled until every required parameter has a value. Templates opened from the Content library use the same strip.

Supported types: string, number, boolean, datetime, date, list, enum[...], json, secret. See Query languages › Parameters.

Run the query​

Click Run (or press Enter). While the run is in flight the button reads Running and the results pane shows progress steps — dispatched, connecting, running, streaming — until the first rows arrive. In Auto mode with a plain-language prompt, the button reads Search and searches your Content library for matching templates instead of running a query. A query you type on Auto runs in its own language instead: the language pill switches to it, and for SQL the dialect follows the tables the query names and the connections in scope. SPL is recognised by its own marks, such as a leading search or index= or | stats, so a pasted Splunk search opens as SPL rather than as KQL. If no connection serves that language, the bar says so and nothing runs. To look up an entity, use the command palette.

A run moves through these states:

StateMeaning
QueuedAccepted and waiting to start.
RunningExecuting; rows stream in as they arrive.
CompletedEvery connection returned.
PartialSome connections failed (for example a rejected credential or an unreachable fleet) and the others returned rows. The rows shown are from the connections that succeeded, and a warning banner says how many failed, for example 3 of 5 connections failed, and lists each cause once with the connections it hit. It reads Partial in amber, not as a failure. Endpoints that didn't answer never make a run partial.
FailedThe run did not complete. A banner shows the reason reported by the run.
CancelledThe run was stopped before completing.

You can keep working elsewhere in Explorer while a run streams; the tab picks it up again when you return.

Endpoint runs stay open​

An osquery run asks every endpoint it targets. Endpoints that are online answer within seconds. An endpoint that is off or asleep answers when it next checks in. So an endpoint run stays open for a while, and its results show as they arrive: you don't have to wait for it to finish to read the rows.

How long a run stays open depends on where it started:

Started fromStays open for
A query tab24 hours
A hunt step or Scout1 hour
A scheduleUntil the schedule's next run, up to 24 hours, unless the schedule sets Keep each run open for (see Schedules)

While a run is open​

The results header and the run's card on the query's Runs tab show who has answered so far, for example 12 of 15 answered · 2 waiting · 1 offline, and Open until the time the run closes. The card also has a progress bar and Cancel.

LabelMeaning
AnsweredThe endpoint returned its rows.
WaitingThe endpoint hasn't answered yet.
OfflineA waiting endpoint that hasn't checked in recently. It's only a label: the run stays open, and the endpoint answers if it comes back before the run closes.
ErroredThe endpoint ran the query and reported an error.

Open a run's per-endpoint table to see each endpoint's status and filter by it.

When a run closes​

A run closes when its time is up. Endpoints that never answered are listed as Didn't answer. That isn't a failure: the run reads Completed, with a note such as 3 endpoints didn't answer before it expired. Their rows are simply missing from this run. A later run picks them up once they're back online.

Replaced by a newer run​

When a schedule fires again while its previous run is still open, the new run replaces the old one. The old run closes, its card says N endpoints didn't answer before a newer run replaced this one, and Open the newer run takes you to it. In the per-endpoint table those endpoints read Replaced. An endpoint that was offline answers only the newest run when it comes back, not every run it missed.

Refine a query in place​

Beta

This feature is currently rolling out and may not be enabled for your organization.

When you edit a query and run it again, the new run replaces the results in the same tab. While it runs, the previous rows stay on screen, dimmed. To keep the old results and run the edited query somewhere else, choose Run in new tab from the ▾ next to Run or from the ⋯ menu, or press ⌥⌘Enter (Mac) or Alt+Ctrl+Enter (Windows/Linux).

The run list. A context row above the results shows Run N of N with ◀ and ▶, then what the run read, for example Ran on Huntbase Lake · Last 24 hours. Step back to an earlier run and its results load from what was stored, without running the query again. Click the label to see every run in this tab. When you're looking at an earlier run, Edit from this run puts that run's query, language and connections back in the bar.

The compact bar. After a run, the query bar shrinks to one row: the language, the query on one line, a summary of the connections and time range, and Run. A dot marks a query you've edited since the last run. Click the row, or press / or ⌘/Ctrl+E, to expand the full bar. Nothing you set is lost when it shrinks.

Work with results​

Query results and Search results use the same frame. Above the results is the context row: the run list, what the run read, Add to hunt and Ask about these results. Then the results header reads, left to right: the views, what was found (for example 42 events · 1.2s · 1 connection), Export, full view and ⋯.

Results open in the view that best fits their shape, and you can switch views in the header. Only views the data supports are offered: an empty run offers Events and Table.

ViewShows
EventsOne collapsed line per event; click a row to expand every field.
TableA column grid — the default for most result sets.
GraphThe entities in the results and how they relate. Offered when rows resolve to entities.
MapRows plotted by location. Offered when rows carry coordinates.

When a query came from a search for one value, such as an IP address, the answer for that value stays above the query's results. Changing the language drops it.

The Fields tab​

The Fields tab in the side panel lists the columns in the results, as Search's does. Each shows how many rows carry it and its top five values, with + and − to include or exclude a value. These queue a filter, like the other filters you pick from results (see Filters wait for Apply). The counts cover the loaded rows, not the whole result, and the tab says so. System fields are hidden.

When nothing matches​

A run that finished and found nothing says so plainly, naming where it looked and over which window, for example No matches in Huntbase Lake for last 24 hours. That's a clean result. A second line, Query looks wrong? Check the schema, opens the schema browser in case the query, not the data, is the problem. If a connection failed, the message says so and doesn't call the result clean.

What the run tells you about itself​

Some runs come back with notices above the results. They are there because a result set that looks complete but isn't is worse than an error:

NoticeWhat it means
Showing the first N rowsA row cap was applied. Add | take N to change it.
Searched N storesA lake query read several stores. Expand it to see which, and narrow to one from there.
N stores were excludedA warning, not a footnote: a store was unavailable, or today's scan budget for your own lakes is used up, so your results may be incomplete. The notice links to the connection so you can see why.
Your lake wasn't searchedThe run didn't ask for your lake, for example a query that Auto ran. Include it runs the query again with your lake.
A column is empty for some eventsNo mapping exists for that field in those events, so the rows are empty rather than guessed.

Lake results also carry a store column showing which store each row came from; you can filter to a single store from a row.

When results contain a timestamp field, a time toolbar and a histogram of events over time appear above the results. Brush the histogram or pick a window to narrow the rows you see; every filter you apply is listed in a filter bar so you can clear them in one place.

Table view with the time histogram, view switcher, Search results box, View Columns and Export controls

Table features​

  • Sort by clicking a column header; click a header's field name to open a field stats popover with top values and cardinality for that column.
  • Filter per column using the filter control in each header, or use Search results… to search across all loaded rows.
  • View Columns shows, hides and reorders columns; drag headers to reorder or resize inline. Reset View returns to the defaults. Column settings belong to the tab, so other query tabs keep their own.
  • Rows load as you scroll — the table keeps fetching until the whole result set is on screen.
  • Right-click a cell that holds a host, user, IP address, hash, domain, URL, email address or process for that value's actions, the same as everywhere else it appears: Ask Scout, Search for this, Open in graph, and Open endpoint for a host in one of your fleets. They sit above the row's own actions.
  • Right-click a row for the row context menu: Copy row JSON, Tag row / Tag cell, Add note / Add cell note, Add to timeline…, Start hunt from this row (or from N rows when several are selected), and Explore in graph. Tags and notes are saved with the row; see Tags and notes and Investigation timeline.
  • Click a row to open the row detail panel beside the table. It shows the key fields, observables you can pivot on, the source endpoint and connection, All fields with copy and filter actions per value, and Provenance (the query and run that produced the row). Copy JSON copies the full row.

Row detail panel open beside the table, showing key observables and the All fields section

Filters wait for Apply​

Beta

This feature is currently rolling out and may not be enabled for your organization.

Filters you pick from the results don't run the query straight away. Click a cell value, a value in the row detail panel, or a top value in a column's field stats (≠ excludes it), and it's queued as a dashed chip in a Not applied row above the results. Queue as many as you need, then click Apply N filters: Huntbase adds them all to the query and runs it once. × on a chip removes that filter, and Discard drops them all.

Filters wait like this on queries that run on your connections, because each run goes to the connection. In a search of your telemetry, a filter you click applies at once.

Export results​

Click Export in the results toolbar and choose Export as CSV or Export as JSON. The export covers every row the run returned, not just the rows loaded on screen. Small exports download immediately; larger ones are prepared in the background — you'll get a notification with a link to the export page, which shows the format, row count and size, and a Download button once the file is ready.

Ask Scout about results​

Beta

This feature is currently rolling out and may not be enabled for your organization.

Click Ask about these results in the context row above the results to ask Scout about this query and its results. Its ▾ has Summarise results for a one-shot summary. A dot on the button means a Scout conversation about this query already exists, and asking continues it. See Chatting with Scout.

Questions about what's on screen go to Scout in the dock, with that context attached. Ask Scout about this row in the row detail panel sends the row itself. After a run, the dock doesn't summarise by itself; click the Summarise results chip when you want a summary. See Scout in the dock.

Add results to a hunt​

Beta

This feature is currently rolling out and may not be enabled for your organization.

Add to hunt in the context row above the results adds this query to a hunt as a step, pinned to the run you're looking at. When the query already belongs to a hunt, it goes to that hunt. Use its ▾ for New hunt from this (first in the menu), or another open or recent hunt. Once added, the tab is linked to the step: the header shows Step with the step's title and Show in notebook, and later runs in this tab update the step. See Add work to a hunt.

A search of your telemetry that you started from a new tab can be added the same way. In its tab, Add to hunt sits next to Save view.

Save and reuse​

After a run, the ⋯ menu next to the editor gains two actions:

  • Save as template opens a modal with Name, Description, Tags, Product (required), Supported Platforms (osquery only), a Parameters editor for anything detected in the query, and a Body preview. Click Save template to add it to Content library › Queries. See Query templates.
  • Start hunt turns the current query and its results into a new hunt. See Hunts.

Query details​

The Query details panel shows everything known about a query and the run on screen. Open it from the results header's ⋯ › Query details. Selecting a row also opens it, on its Row tab. Its other tabs are Details (the default), Entities, Runs, Schedules, Sessions and, for a query from a template, Template.

The Details tab has:

SectionWhat it shows
This runStatus, rows (and whether the engine capped them), when it ran and how long it took, who ran it and why (By hand, By Scout, From a hunt, On a schedule, Through the API), the organisation, the time range in words, the engine, and any parameter values.
Errors and warningsThe failure, endpoint errors, and the same notices the results show, such as a row cap or stores that were skipped.
ConnectionsEach connection's status, rows and its own error, including connections that failed before returning anything.
QueryThe query, laid out to read. When what ran differs from what you wrote, a Translated query (for a search) or Executed query (after parameters were filled in) section shows it.
LinkedThe hunt and cell it belongs to, the saved query, the query it was edited from, and the Scout conversation.
RunsThe latest five runs. Click one to show it. All runs opens the Runs tab.
About this queryCollapsed: who created it and when, total runs and rows, and its ids.

Share a saved query​

Where the new sharing screens are on, the Query details panel's ⋯ menu has Share…, which opens the Share dialog: give people Use (see and run the query) or Edit (change it), or restrict it to the people you name. Queries are shared with people, not teams.

Query history​

Every run is recorded in Query history: every query that ran, by hand, by Scout or on a schedule, grouped by query, with its status, connections and row count. Under the new navigation it's Detect & automate › Query history. In the classic layout, it's Activity › Queries. Open a run there and click Open query to bring it back into Explorer.

A run that has already finished opens as finished: its results load from what was stored, and the Run button and run list don't show it as running while they load. Only a run that is really still going reads Running.

Next steps​

  • Query languages — syntax and examples for every language
  • Query templates — save, share and parameterize queries
  • Schedules — run a query on a recurring schedule
  • Search telemetry — search your shipped telemetry, filter it by clicking, then show it as a query
  • Hunts — escalate a query result into a hunt