<commit_before>---
pageid: cmd.query
title: query
layout: docs
section: Commands
permalink: docs/cmd/query.html
---

*Since 1.6.*

```bash
$ watchman -j <<-EOT
["query", "/path/to/root", {
  "suffix": "php",
  "expression": ["allof",
    ["type", "f"],
    ["not", "empty"],
    ["ipcre", "test", "basename"]
  ],
  "fields": ["name"]
}]
EOT
```

Executes a query against the specified root. This example uses the `-j` flag to
the watchman binary that tells it to read stdin and interpret it as the JSON
request object to send to the watchman service.  This flag allows you to send
in a pretty JSON object (as shown above), but if you're using the socket
interface you must still format the object as a single line JSON request as
documented in the protocol spec.

The first argument to query is the path to the watched root.  The second
argument holds a JSON object describing the query to be run.  The query object
is processed by passing it to the query engine (see [File Queries](
/watchman/docs/file-query.html)) which will generate a set of matching files.

The query command will then consult the `fields` member of the query object;
if it is not present it will default to:

```json
"fields": ["name", "exists", "new", "size", "mode"]
```

For each file in the result set, the query command will generate a JSON object
value populated with the requested fields.  For example, the default set of
fields will return a response something like this:

```json
{
    "version": "2.9",
    "clock": "c:80616:59",
    "is_fresh_instance": false,
    "files": [
        {
            "exists": true,
            "mode": 33188,
            "new": false,
            "name": "argv.c",
            "size": 1340,
        }
    ]
}
```

For queries using the `since` generator, the `is_fresh_instance` member is true<commit_msg>Document error values for fields<commit_after>---
pageid: cmd.query
title: query
layout: docs
section: Commands
permalink: docs/cmd/query.html
---

*Since 1.6.*

```bash
$ watchman -j <<-EOT
["query", "/path/to/root", {
  "suffix": "php",
  "expression": ["allof",
    ["type", "f"],
    ["not", "empty"],
    ["ipcre", "test", "basename"]
  ],
  "fields": ["name"]
}]
EOT
```

Executes a query against the specified root. This example uses the `-j` flag to
the watchman binary that tells it to read stdin and interpret it as the JSON
request object to send to the watchman service.  This flag allows you to send
in a pretty JSON object (as shown above), but if you're using the socket
interface you must still format the object as a single line JSON request as
documented in the protocol spec.

The first argument to query is the path to the watched root.  The second
argument holds a JSON object describing the query to be run.  The query object
is processed by passing it to the query engine (see [File Queries](
/watchman/docs/file-query.html)) which will generate a set of matching files.

The query command will then consult the `fields` member of the query object;
if it is not present it will default to:

```json
"fields": ["name", "exists", "new", "size", "mode"]
```

For each file in the result set, the query command will generate a JSON object
value populated with the requested fields.  For example, the default set of
fields will return a response something like this:

```json
{
    "version": "2.9",
    "clock": "c:80616:59",
    "is_fresh_instance": false,
    "files": [
        {
            "exists": true,
            "mode": 33188,
            "new": false,
            "name": "argv.c",
            "size": 1340,
        }
    ]
}
```

If a field's value cannot be computed, a field's value may be `null`, or may
be an object with an `error` key containing a descriptive message string:

```json
{
    "version": "2019-07-22T13:50:36Z",
    "is_fresh_instance": false,
    "clock": "c:1563834049:1830370:791543813:2257494",
    "files": [
        {
            "content.sha1hex": null,
            "name": "docs"
            "symlink_target": null,
            "type": "d",
        },
        {
            "content.sha1hex": {
                "error": "eloop: file is a symlink: Invalid argument: Invalid argument"
            },
            "type": "l",
            "symlink_target": "eloop",
            "name": "eloop"
        }
    ]
}
```

For queries using the `since` generator, the `is_fresh_instance` member is true
{'fraction_non_alphanumeric': 0.12096958609650126, 'fraction_numerical': 0.020352160987880175, 'mean_word_length': 2.9476534296028882, 'pattern_counts': {'":': 39, '<': 7, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6180057', 'n_tokens_mistral': 1381, 'n_tokens_neox': 1292, 'n_words': 566}