---
sidebar:
  hidden: true
title: roboto.domain.triggers.query_templates
---
## Module Contents

### QUERY_FIELD

```python
roboto.domain.triggers.query_templates.QUERY_FIELD = 'query'
```

`from roboto.domain.triggers.query_templates import QUERY_FIELD`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/triggers/query_templates.py#L12-L12)

Selector field holding a RoboQL query, the one field of an invocation input whose value is an expression rather than a value the expression compares against.

### QueryPlaceholder

```python
class roboto.domain.triggers.query_templates.QueryPlaceholder
```

`from roboto.domain.triggers.query_templates import QueryPlaceholder`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/triggers/query_templates.py#L20-L34)

Bases: `NamedTuple`

One `{{placeholder}}` found in a RoboQL query, and the literal enclosing it.

**Attributes**

- **QueryPlaceholder.end** (`int`) = `0`: Index one past the placeholder's last character.
- **QueryPlaceholder.name** (`str`): The placeholder's dotted name, without the braces.
- **QueryPlaceholder.quote** (`str | None`) = `None`: The quote character of the string literal the placeholder sits in, or `None` when it sits in expression text (a comment counts as expression text: a value could close it).
- **QueryPlaceholder.start** (`int`) = `0`: Index of the placeholder's first character in the query.

### escape_string_literal()

```python
def roboto.domain.triggers.query_templates.escape_string_literal(
    value: str,
    quote: str,
) -> str
```

`from roboto.domain.triggers.query_templates import escape_string_literal`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/triggers/query_templates.py#L105-L122)

Return `value` escaped for splicing inside a `quote`-delimited RoboQL string literal.

**Parameters**

- **value** (`str`): The value to splice.
- **quote** (`str`): The literal's delimiter, `"` or `'`.

**Raises**

- `ValueError`: `value` holds a character the literal cannot carry under any escape, namely a carriage return or a newline.

**Returns**

- `str`

### iter_query_templates()

```python
def roboto.domain.triggers.query_templates.iter_query_templates(
    invocation_input: collections.abc.Mapping[str, Any],
) -> collections.abc.Iterator[str]
```

`from roboto.domain.triggers import iter_query_templates`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/triggers/query_templates.py#L177-L186)

Yield every RoboQL query in `invocation_input`, in document order.

**Parameters**

- **invocation_input** (`collections.abc.Mapping[str, Any]`)

**Returns**

- `collections.abc.Iterator[str]`

### map_query_templates()

```python
def roboto.domain.triggers.query_templates.map_query_templates(
    invocation_input: collections.abc.Mapping[str, Any],
    transform: collections.abc.Callable[[str], str],
) -> dict[str, Any]
```

`from roboto.domain.triggers import map_query_templates`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/triggers/query_templates.py#L154-L174)

Return `invocation_input` with `transform` applied to every RoboQL query it holds.

**Parameters**

- **invocation_input** (`collections.abc.Mapping[str, Any]`): An [`InvocationInput`](/reference/python-sdk/roboto/domain/actions/invocation_record#roboto.domain.actions.invocation_record.InvocationInput) in its JSON form, whose top-level values are selectors or lists of them.
- **transform** (`collections.abc.Callable[[str], str]`): Called with each selector's query; its result replaces that query.

**Returns**

- `dict[str, Any]`: A copy, shallow below the selectors it rewrites.

### placeholders_outside_string_literals()

```python
def roboto.domain.triggers.query_templates.placeholders_outside_string_literals(
    query: str,
) -> list[str]
```

`from roboto.domain.triggers.query_templates import placeholders_outside_string_literals`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/triggers/query_templates.py#L89-L102)

Return the placeholders in `query` that do not sit inside a string literal.

A value spliced inside a literal can be escaped into it (see [`escape_string_literal()`](/reference/python-sdk/roboto/domain/triggers/query_templates#roboto.domain.triggers.query_templates.escape_string_literal)), so it can only ever be data. A value spliced anywhere else becomes query syntax: a tag or path carrying an operator would rewrite the query it was meant to be compared against.

**Parameters**

- **query** (`str`): A RoboQL query, possibly carrying `{{placeholder}}` templates.

**Returns**

- `list[str]`: The names of those placeholders, in the order they appear.

### scan_placeholders()

```python
def roboto.domain.triggers.query_templates.scan_placeholders(
    query: str,
) -> list[QueryPlaceholder]
```

`from roboto.domain.triggers.query_templates import scan_placeholders`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/triggers/query_templates.py#L37-L86)

Return every `{{placeholder}}` in `query`, each with the literal enclosing it.

Follows the lexical rules of the RoboQL grammar: both quote characters open a string literal, a backslash inside one escapes the next character, and `//` and slash-star comments run to their terminator.

**Parameters**

- **query** (`str`): A RoboQL query, possibly carrying `{{placeholder}}` templates.

**Returns**

- `list[QueryPlaceholder]`

### substitute_query_template()

```python
def roboto.domain.triggers.query_templates.substitute_query_template(
    query: str,
    resolve: collections.abc.Callable[[str], str],
) -> str
```

`from roboto.domain.triggers import substitute_query_template`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/triggers/query_templates.py#L125-L151)

Return `query` with each placeholder replaced by `resolve`'s value for it, escaped in place.

Each placeholder is substituted exactly once, and a value is escaped for the literal that encloses it, so a value that itself looks like a template or carries a quote stays data.

**Parameters**

- **query** (`str`): A RoboQL query carrying `{{placeholder}}` templates.
- **resolve** (`collections.abc.Callable[[str], str]`): Returns the value for a placeholder name.

**Raises**

- `ValueError`: A placeholder sits outside a string literal, or a value cannot be escaped into the literal it lands in.

**Returns**

- `str`