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

# Execute Queries

> Overview of the Trench API

<Info>This endpoint requires your [private API key](/api-reference/overview#authentication).</Info>

This endpoint allows you to execute read-only queries against your Trench data.
The endpoint will proxy the request to the underlying ClickHouse database.
For more information about ClickHouse's query language, see the [official documentation](https://clickhouse.com/docs/en/sql-reference).

## Examples

### Quering event properties, context, and traits

To query a specific nested property, you can use the `JSONExtract` function. For example, to query all events where the `totalAccounts` property is greater than 3, you can use the following query:

```sql theme={null}
SELECT * FROM events WHERE JSONExtract(properties, 'totalAccounts', 'UInt64') > 3
```

Similarly, you can query the context and traits:

```sql theme={null}
SELECT * FROM events WHERE JSONExtract(context, 'country', 'String') = 'Denmark'
```

### Joining identified users with their events

All `identify` calls are sent to the same underlying `events` ClickHouse table, so you can join events with identified users using the `userId` column. For example, to query all events for a user with the ID `user-123`, you can use the following query:

```sql theme={null}
SELECT * FROM events WHERE userId = 'user-123'
```

To get the tracking events and the user's most recently provided email, you can join the `track` and `identify` event types:

```sql theme={null}
SELECT 
    i.email,
    e.*
FROM 
    events e 
LEFT JOIN 
    (SELECT userId, type, JSONExtract(traits, 'email', 'String') AS email FROM events) i 
ON 
    e.userId = i.userId
WHERE 
    e.type = 'track' 
    AND i.type = 'identify';
```


## OpenAPI

````yaml post /queries
openapi: 3.0.0
info:
  title: trench API
  description: ''
  version: '1.0'
  contact: {}
servers: []
security: []
tags: []
paths:
  /queries:
    post:
      summary: Execute queries via SQL. Requires private API key in Bearer token.
      operationId: QueriesController_executeQueries
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueriesDTO'
      responses:
        '200':
          description: The queries have been successfully executed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedQueryResponse'
components:
  schemas:
    QueriesDTO:
      type: object
      properties:
        queries:
          description: The queries to execute.
          example:
            - SELECT COUNT(*) FROM events WHERE event = "UserSignedUp"
          type: array
          items:
            type: string
      required:
        - queries
    PaginatedQueryResponse:
      type: object
      properties:
        limit:
          type: number
          description: The limit of the pagination.
          nullable: true
        offset:
          type: number
          description: The offset of the pagination.
          nullable: true
        total:
          type: number
          description: The total number of results. If `null`, the total is unknown.
          nullable: true
        results:
          description: >-
            The results of the queries, returned in the same order as the
            queries.
          example:
            - results:
                - count: 3485241
          type: array
          items:
            type: object
      required:
        - limit
        - offset
        - total
        - results

````