> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getprimo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Queries

> Write osquery SQL to read live data from your macOS, Windows, and Linux devices, run it on demand, or schedule it and export each device's results.

**Queries** let you ask your devices a question in SQL and read their answers. Primo runs each query through osquery on the Primo agent, so you can read data such as installed apps, running processes, or disk encryption status straight from the device.

You can use a query in two ways:

* **Live run**: ask the targeted devices now and watch their answers come in.
* **Scheduled**: set an interval so each device runs the query on its own and keeps its last result, even while you are away.

## Requirements

* Devices running macOS, Windows, or Linux, enrolled in Primo with the Primo agent installed. Queries don't run on iOS, iPadOS, or Android.
* The MDM read permission to see the **Queries** page, and the MDM write permission to add, edit, delete, and run queries.

## Open Queries

Go to **MDM** > **Queries**. The list shows every query with its **OS**, **Interval**, **Performance impact**, and **Target**. Queries marked **Managed by Primo** come with Primo: you can run them and read their results, but you can't edit or delete them.

## Add a query

**1. Open the form**

Go to **MDM** > **Queries** and click **Add a query**.

**2. Describe the query**

Under **Configuration**, enter a **Name** and, optionally, a **Description** of what the query reports.

**3. Write the SQL**

Write the query in the **SQL** editor, for example:

```sql theme={null}
SELECT name, version FROM apps;
```

The **Tables** panel lists the osquery tables you can read, with their columns and the platforms that support them. Primo shows the platforms your query is **Compatible with** from the tables it reads. A query that mixes tables with no platform in common can't be saved.

**4. Choose how often it runs**

Pick an **Interval**: **Never**, or from every 5 minutes to every day. The default is every hour. Each device runs the query at that interval and keeps its last result. **Never** keeps the query for live runs only.

**5. Choose the target**

Under **Target**, pick **Target all devices** or **Target by device group**, then select the device groups. Primo previews how many devices are targeted.

**6. Save the query**

Click **Add query**.

> [!TIP]
>
> Click **Run query** before you save to test the SQL on the target and check the answers.

## Run a query live

**1. Open the query**

Go to **MDM** > **Queries** and click the query.

**2. Start the live run**

Open the actions menu and click **Run live query**.

**3. Read the answers**

The status shows how many devices responded, for example **Running · 12/40**. Offline devices, devices that can't run the query, and devices not enrolled in the MDM are counted apart. Click **Stop** to end the run early, or **Export CSV** to download the answers.

A live run asks a limited number of devices at once. When the target is too large, narrow it to a device group, or set an interval to collect results from every device.

## Read scheduled results

Click a query that runs on an interval to see each device's last answer, with its **Device** and **Last fetched** time. Filter by device, or open the actions menu and click **Export CSV** to download the results. A **Clipped** badge means the report reached its row limit and some devices are missing.

A query set to **Never** stores no results: edit it and pick an interval to see them here.

## See a device's query results

Open a macOS, Windows, or Linux device and select the **Queries** tab. It lists the saved queries that stored a result for this device, with their **Results** count and **Last fetched** time.

* Click a query to open its results filtered to this device.
* Open a row's actions menu and click **Run on this device** to run that query live on this device only.
* Click **Run a live query** to write a new query that targets this device only. A query that targets a single device can be run but not saved.

## Edit or delete a query

Go to **MDM** > **Queries**, open the row's actions menu, and click **Edit query** or **Delete query**. Deleting a query also deletes the results it stored.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.