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

# DB Query Templatization

> This action templatizes database query text by replacing number and string literals with placeholders to reduce cardinality.

## Considerations

<Warning>
  Before enabling **DB query templatization**, please note the following:

  * The action rewrites `db.query.text` (or the deprecated `db.statement`) in place when present.
  * Number and string literals are replaced with `?`. Identifiers, bind/positional parameters, booleans, and `NULL` are left unchanged.
  * Spans without a `db.system.name` (or the deprecated `db.system`) attribute, or with a known non-SQL system (e.g. MongoDB, Redis), are skipped.
</Warning>

## Use Cases

**Cardinality control**

* Raw SQL with embedded literals (e.g. `WHERE id = 1` vs `WHERE id = 2`) creates high-cardinality query attributes and span names. Templatizing literals collapses those into a shared template such as `WHERE id = ?`.

**Cost and backend indexing**

* Lower cardinality on database spans improves aggregations, span metrics, and indexing in your observability backend, and can reduce storage volume.

**Sensitive values in queries**

* Replacing string and number literals removes many accidental secrets or PII that were inlined into SQL (passwords, emails, IDs) while keeping the query structure intact.

## Configuration Options

The DbQueryTemplatization action is configured using the `odigos.io/v1alpha1.Action` CRD with the `dbQueryTemplatization` configuration section.

<AccordionGroup>
  <Accordion title="actionName">
    **actionName** `string` : Allows you to attach a meaningful name to the action for convenience.

    * This field is *optional*
    * <Icon icon="triangle-exclamation" iconType="solid" color="yellow" /> Odigos does not use or assume any meaning from this field
  </Accordion>

  <Accordion title="notes">
    **notes** `string` : Allows you to attach notes regarding the action for convenience.

    * This field is *optional*
    * <Icon icon="triangle-exclamation" iconType="solid" color="yellow" /> Odigos does not use or assume any meaning from this field
  </Accordion>

  <Accordion title="disabled">
    **disabled** `boolean` : Allows you to temporarily disable the action, but keep it saved for future use.

    * This field is *optional*, and defaults to `false`
  </Accordion>

  <Accordion title="signals *">
    **signals** `string[]` : An array with the signals that the action will operate on.

    * This field is *required*
    * Supported values: `TRACES`
  </Accordion>

  <Accordion title="dbQueryTemplatization *">
    **dbQueryTemplatization** `object` : Configuration for the DbQueryTemplatization action.

    * This field is *required* for this action type

    <AccordionGroup>
      <Accordion title="scopes">
        **scopes** `object` : Limits which sources this templatization config applies to.

        * This field is *optional*
        * If unset or empty, the config is applied to all sources.
        * If multiple source scopes are set, they must all match simultaneously (AND logic).

        <AccordionGroup>
          <Accordion title="sources">
            **sources** `object[]` : A list of workloads to apply this action to.

            * Each entry requires `name`, `namespace`, and `kind` (`Deployment`, `StatefulSet`, etc.).
          </Accordion>

          <Accordion title="namespaces">
            **namespaces** `string[]` : Apply this action to all sources in the listed namespaces.
          </Accordion>

          <Accordion title="languages">
            **languages** `string[]` : Apply this action only to containers instrumented with the listed programming languages.
          </Accordion>
        </AccordionGroup>
      </Accordion>

      <Accordion title="templatizeLiterals">
        **templatizeLiterals** `boolean` : When enabled, number and string literals in SQL queries are replaced with placeholders.

        * This field is *optional*, and defaults to `false`
        * What is templatized:
          * number literals (e.g. `1`, `3.14`)
          * string literals (e.g. `'alice'`)
        * What is **not** templatized:
          * identifiers (table names, column names, etc.)
          * positional parameters (e.g. `$1`)
          * bind parameters (e.g. `:name`)
          * boolean literals and `NULL`
          * keywords, operators, punctuation, whitespace, comments, etc.
      </Accordion>
    </AccordionGroup>
  </Accordion>
</AccordionGroup>

## Basic Example

Given a span with:

```text theme={null}
db.query.text: SELECT * FROM users WHERE id = 1 AND name = 'alice'
```

the action rewrites it to:

```text theme={null}
db.query.text: SELECT * FROM users WHERE id = ? AND name = ?
```

<Steps>
  <Step>
    Create a YAML file with the following content:

    ```yaml db-query-templatization.yaml theme={null}
    apiVersion: odigos.io/v1alpha1
    kind: Action
    metadata:
      name: db-query-templatization
      namespace: odigos-system
    spec:
      actionName: DB Query Templatization
      signals:
        - TRACES
      dbQueryTemplatization:
        templatizeLiterals: true
    ```
  </Step>

  <Step>
    Apply the action to the cluster:

    ```bash theme={null}
    kubectl apply -f db-query-templatization.yaml
    ```
  </Step>
</Steps>

## Scoped Example

To limit templatization to specific workloads, add `scopes`. Omit `scopes` (or leave it empty) to apply the action to all sources.

```yaml db-query-templatization-scoped.yaml theme={null}
apiVersion: odigos.io/v1alpha1
kind: Action
metadata:
  name: db-query-templatization-my-app
  namespace: odigos-system
spec:
  actionName: DB Query Templatization for my-app
  signals:
    - TRACES
  dbQueryTemplatization:
    scopes:
      sources:
        - name: my-app
          namespace: default
          kind: Deployment
    templatizeLiterals: true
```

<Tip>
  Pair this action with [Infer DB Attributes](./inferdbattributes) so database spans get both templatized query text and inferred `db.operation.name` / `db.collection.name` attributes.
</Tip>