---
id: query-execute
title: "Execute a data lake query"
description: "Execute a read-only SQL query against the audit data lake."
sidebar_label: "Execute a data lake query"
hide_title: true
hide_table_of_contents: true
api: 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
sidebar_class_name: "post api-method"
info_path: docs/api/data-lake
custom_edit_url: null
---

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Execute a data lake query"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/data/lake/query"}
  context={"endpoint"}
>
  
</MethodEndpoint>



Execute a read-only SQL query against the audit data lake.

The SQL statement can be sent in three ways:
- As a JSON body: `{ "query": "SELECT ..." }`
- As a plain text body with `Content-Type: text/plain`
- As a `query` query string parameter

> ℹ️ **Note:** If you provide the SQL in both the query string and the body, they must be identical or the request will fail.

Results stream directly from ClickHouse. By default, the response uses tab-separated format. Add a `FORMAT JSON` clause to your SQL to get JSON output.


<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"in":"query","name":"query","schema":{"type":"string","minLength":1,"maxLength":50000},"required":false,"description":"The SQL query to execute. Must be a read-only, single statement.","example":"SELECT * FROM audit_log LIMIT 10"},{"in":"query","name":"param_user_id","schema":{"type":"string"},"required":false,"description":"Parametrized query value. Use the `param_` prefix followed by the parameter name.\n\nYou can pass multiple parameters by adding additional `param_*` query string parameters (e.g., `param_org_id`, `param_start_date`). Each parameter maps to a `{name:Type}` placeholder in the SQL query.\n","example":"42"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"description":"The SQL query to execute. Accepts JSON or plain text.","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":50000,"description":"The SQL query to execute.","example":"SELECT * FROM audit_log LIMIT 10 FORMAT JSON"}},"required":["query"]},"example":{"query":"SELECT * FROM audit_log LIMIT 10 FORMAT JSON"}},"text/plain":{"schema":{"type":"string","minLength":1,"maxLength":50000,"description":"The SQL query as a plain text string.","example":"SELECT * FROM audit_log LIMIT 10"}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Query executed successfully. The response body contains the query results in the requested format.","content":{"text/tab-separated-values":{"schema":{"type":"string"},"example":"1\tuser@example.com\t2024-01-15 10:30:00\n2\tadmin@example.com\t2024-01-15 11:00:00\n"},"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Column name."},"type":{"type":"string","description":"Column data type."}}},"description":"Column metadata for the result set."},"data":{"type":"array","items":{"type":"object"},"description":"Array of result rows."},"rows":{"type":"integer","description":"Total number of rows returned."}}},"example":{"meta":[{"name":"id","type":"UInt64"},{"name":"user_email","type":"String"},{"name":"created_at","type":"DateTime"}],"data":[{"id":1,"user_email":"user@example.com","created_at":"2024-01-15 10:30:00"},{"id":2,"user_email":"admin@example.com","created_at":"2024-01-15 11:00:00"}],"rows":2}}}},"400":{"description":"Invalid SQL query. The query failed validation (not read-only, multiple statements, or exceeds 50,000 characters).","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code.","example":400},"code":{"type":"string","description":"Machine-readable error code.","example":"FST_ERR_INVALID_SQL"},"error":{"type":"string","description":"HTTP status text.","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error description.","example":"SQL query must be read-only"}},"required":["statusCode","error","message"],"title":"Error"},"example":{"statusCode":400,"code":"FST_ERR_INVALID_SQL","error":"Bad Request","message":"SQL query must be read-only"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code.","example":400},"code":{"type":"string","description":"Machine-readable error code.","example":"FST_ERR_INVALID_SQL"},"error":{"type":"string","description":"HTTP status text.","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error description.","example":"SQL query must be read-only"}},"required":["statusCode","error","message"],"title":"Error"},"example":{"statusCode":401,"code":"FST_ERR_AUTHENTICATION","error":"Unauthorized","message":"Authentication failed"}}}},"403":{"description":"Forbidden. Either the token has no granted resources or the query matches an AST restriction.","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code.","example":400},"code":{"type":"string","description":"Machine-readable error code.","example":"FST_ERR_INVALID_SQL"},"error":{"type":"string","description":"HTTP status text.","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error description.","example":"SQL query must be read-only"}},"required":["statusCode","error","message"],"title":"Error"},"examples":{"authorization":{"summary":"No granted resources","value":{"statusCode":403,"code":"FST_ERR_AUTHORIZATION","error":"Forbidden","message":"No resources granted for action governance:lake:read"}},"forbidden_sql":{"summary":"AST restriction violation","value":{"statusCode":403,"code":"FST_ERR_FORBIDDEN_SQL","error":"Forbidden","message":"SQL query contains forbidden expressions"}}}}}},"409":{"description":"ClickHouse returned an error while executing the query.","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code.","example":400},"code":{"type":"string","description":"Machine-readable error code.","example":"FST_ERR_INVALID_SQL"},"error":{"type":"string","description":"HTTP status text.","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error description.","example":"SQL query must be read-only"}},"required":["statusCode","error","message"],"title":"Error"},"example":{"statusCode":409,"code":"FST_ERR_CLICKHOUSE_QUERY","error":"Conflict","message":"ClickHouse query execution failed"}}}},"429":{"description":"Rate limit exceeded. Maximum 60 requests per minute per token.","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code.","example":400},"code":{"type":"string","description":"Machine-readable error code.","example":"FST_ERR_INVALID_SQL"},"error":{"type":"string","description":"HTTP status text.","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error description.","example":"SQL query must be read-only"}},"required":["statusCode","error","message"],"title":"Error"},"example":{"statusCode":429,"code":"FST_ERR_RATE_LIMIT","error":"Too Many Requests","message":"Rate limit exceeded, retry in 30 seconds"}}}}}}
>
  
</StatusCodes>