---
title: "Queries Module"
url: https://develop.sentry.dev/sdk/telemetry/traces/modules/queries/
---

# Queries Module

The SDK should auto-instrument all database queries, and each query to the database should result in a span. This includes queries made manually, or via ORM. The Queries module supports SQL databases like PostgreSQL and MySQL, as well as MongoDB. It does not support other databases like Neo4j or ClickHouse. Regardless of that, the SDK should instrument database queries as fully and correctly as possible to ensure correct behavior and future compatibility.

## [Span Attributes](https://develop.sentry.dev/sdk/telemetry/traces/modules/queries.md#span-attributes)

| Attribute     | Description                                                                                                                                                   | Notes                                                                                                                                   |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `op`          | Prefixed with `"db"` (e.g., `"db"`, `"db.query"`, `"db.sql.query"`) [1](https://develop.sentry.dev/sdk/telemetry/traces/modules/queries.md#user-content-fn-1) | Required                                                                                                                                |
| `description` | The full scrubbed query (e.g., `SELECT * FROM users where id = ?`)                                                                                            | Required, see [Query Scrubbing](https://develop.sentry.dev/sdk/telemetry/traces/modules/queries.md#query-scrubbing) for details         |
| `data`        | A key-value mapping of span attributes. (e.g., `{"db.system": "postgresql", "db.name": "prod-2"}`)                                                            | Required for full experience. See [Span Data](https://develop.sentry.dev/sdk/telemetry/traces/modules/queries.md#span-data) for details |

### [Query Scrubbing](https://develop.sentry.dev/sdk/telemetry/traces/modules/queries.md#query-scrubbing)

The query description should be scrubbed of any user-supplied values.

e.g., the query

```sql
SELECT * FROM users WHERE id = 17;
```

should be scrubbed to:

```sql
SELECT * FROM users WHERE id = ?;
```

The `?` parameter is a placeholder in the query. The SDK must scrub out all values and replace them with a placeholder. Supported placeholder values are `%s`, `?`, `:c0` (e.g., `:c0`, `:c1`) and `$1` (e.g., `$1`, `$2`).

For MongoDB, the description should contain valid JSON. If replacing values with a placeholder, the string `"?"` should be used.

```json
{ "find": "documents", "filter": { "wordCount": { "$gte": "?" } } }
```

### [Span Data](https://develop.sentry.dev/sdk/telemetry/traces/modules/queries.md#span-data)

For full support, each database span should have a `data` attribute. `data` is itself a key-value lookup of attributes. Refer to [Database Span Data Conventions](https://develop.sentry.dev/sdk/performance/span-data-conventions.md#database) for a full list of attributes that database spans should have. We recommend that the SDK provide *all* of those attributes for every span. However, the *minimal* requirement is that the SDK provides the `db.system` attribute.

#### [MongoDB Data](https://develop.sentry.dev/sdk/telemetry/traces/modules/queries.md#mongodb-data)

MongoDB support requires a few extra data attributes. In addition to a `db.system` value of `"mongodb"`, the `db.operation` and `db.collection.name` attributes are also required to contain the command and collection name respectively.

## [SQL Instrumentation Example](https://develop.sentry.dev/sdk/telemetry/traces/modules/queries.md#sql-instrumentation-example)

Consider a hypothetical Python ORM:

```python
from magicORM import ORM
from .models import User, Product

ORM.connect_postgres(host="127.0.0.1", port="7777", database="production")
return User.find(17).find_related(Product)
```

Assume it makes this SQL query:

```sql
SELECT * FROM projects
WHERE projects_user = 17;
```

This should result in the following span:

```json
{
  "description": "SELECT * FROM projects WHERE projects_user = 17",
  "op": "db",
  "data": {
    "db.system": "postgresql",
    "db.operation": "SELECT",
    "db.name": "production",
    "server.address": "127.0.0.1",
    "server.port": "7777"
  }
}
```

## [Footnotes](https://develop.sentry.dev/sdk/telemetry/traces/modules/queries.md#footnote-label)

1. Some operations are accepted by Sentry, but not indexed by the Queries module. This includes `db.sql.room`, `db.redis`, and some others. Do not attempt to trick the system by providing an incorrect span operation! [↩](https://develop.sentry.dev/sdk/telemetry/traces/modules/queries.md#user-content-fnref-1)