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

# GRAPH.QUERY

> Executes the given query against a specified graph

Executes the given query against a specified graph.

Arguments: `Graph name, Query, [timeout], [--compact], [version]`

Returns: [Result set](/design/result-structure)

| Optional argument | Description                                                                                                                                                                                          |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `timeout`         | Query-level timeout in milliseconds. See [the configuration section](/getting-started/configuration#timeout).                                                                                        |
| `--compact`       | Returns results in [compact format](/design/client-spec#retrieving-the-compact-result-set).                                                                                                          |
| `version`         | Graph version number. When provided, the server rejects the query with a `version mismatch` error if the current graph version doesn't match, allowing clients to invalidate cached schema mappings. |

## Queries and Parameterized Queries

The execution plans of queries, both regular and parameterized, are cached (up to [CACHE\_SIZE](/getting-started/configuration#cache_size) unique queries are cached). Therefore, it is recommended to use parameterized queries when executing many queries with the same pattern but different constants.

Query-level timeouts can be set as described in [the configuration section](/getting-started/configuration#timeout).

### Command structure

`GRAPH.QUERY graph_name "query" [timeout value] [--compact] [version value]`

example:

<CodeGroup>
  ```python Python theme={null}
  graph.query("MATCH (p:president)-[:born]->(:state {name:'Hawaii'}) RETURN p")
  ```

  ```javascript JavaScript theme={null}
  const result = await graph.query("MATCH (p:president)-[:born]->(:state {name:'Hawaii'}) RETURN p");
  console.log(result);
  ```

  ```java Java theme={null}
  ResultSet result = graph.query("MATCH (p:president)-[:born]->(:state {name:'Hawaii'}) RETURN p");
  System.out.println(result);
  ```

  ```rust Rust theme={null}
  let result = graph.query(r#"MATCH (p:president)-[:born]->(:state {name:'Hawaii'}) RETURN p"#).execute().await?;
  println!("{:?}", result);
  ```

  ```bash Shell theme={null}
  GRAPH.QUERY us_government "MATCH (p:president)-[:born]->(:state {name:'Hawaii'}) RETURN p"
  ```
</CodeGroup>

### Parameterized query structure:

`GRAPH.QUERY graph_name "CYPHER param=val [param=val ...] query"`

example:

<CodeGroup>
  ```python Python theme={null}
  graph.query("MATCH (p:president)-[:born]->(:state {name:$state_name}) RETURN p", {'state_name': 'Hawaii'})
  ```

  ```javascript JavaScript theme={null}
  const result = await graph.query(
    "MATCH (p:president)-[:born]->(:state {name:$state_name}) RETURN p",
    { params: { state_name: "Hawaii" } }
  );
  console.log(result);
  ```

  ```java Java theme={null}
  Map<String, Object> params = new HashMap<>();
  params.put("state_name", "Hawaii");
  ResultSet result = graph.query(
    "MATCH (p:president)-[:born]->(:state {name:$state_name}) RETURN p",
    params
  );
  System.out.println(result);
  ```

  ```rust Rust theme={null}
  let params = std::collections::HashMap::from([
      ("state_name", "Hawaii")
  ]);
  let result = graph.query_with_params(
      r#"MATCH (p:president)-[:born]->(:state {name:$state_name}) RETURN p"#,
      &params
  ).execute().await?;
  println!("{:?}", result);
  ```

  ```bash Shell theme={null}
  GRAPH.QUERY us_government "CYPHER state_name='Hawaii' MATCH (p:president)-[:born]->(:state {name:$state_name}) RETURN p"
  ```
</CodeGroup>

## Query language

The syntax is based on [Cypher](http://www.opencypher.org/). [Most](/cypher/cypher-support) of the language is supported. See [Cypher documentation](/cypher).

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Why should I use parameterized queries instead of string interpolation?">
    Parameterized queries allow FalkorDB to cache and reuse execution plans across queries that differ only in their constant values. This significantly improves performance. They also prevent Cypher injection attacks.
  </Accordion>

  <Accordion title="What happens when a query exceeds the timeout?">
    When a query exceeds the configured timeout (in milliseconds), it is terminated and an error is returned to the client. You can set timeouts per-query using the `TIMEOUT` argument, or globally via `GRAPH.CONFIG SET TIMEOUT_DEFAULT` and `TIMEOUT_MAX`.
  </Accordion>

  <Accordion title="What does the --compact flag do?">
    The `--compact` flag returns results in a compact format that uses internal IDs instead of string labels and property names. This reduces network bandwidth and is intended for use by client libraries that maintain their own schema cache.
  </Accordion>

  <Accordion title="What is the version parameter used for?">
    The `version` parameter enables optimistic schema caching. When a client provides a version number that does not match the current graph version, the server returns a `version mismatch` error, signaling the client to refresh its cached schema mappings.
  </Accordion>

  <Accordion title="Are execution plans cached automatically?">
    Yes. FalkorDB caches execution plans for up to `CACHE_SIZE` unique queries (configurable). Both regular and parameterized queries benefit from plan caching.
  </Accordion>
</AccordionGroup>