# Query builders

Build SurrealQL statements fluently with the Mojo SDK query builders.

The Mojo SDK ships a set of fluent builders that construct SurrealQL statements for you. Each builder is `Copyable` and `Movable`, so you can chain calls or pass it around, and each has a `build()` method that returns the statement as a string.

```python
var qb = client.select_builder("person")
    .fields("id, name, age")
    .where_clause("age >= 18")
    .order_by("age DESC")
    .limit(20)

var resp = client.query_select(qb)
```

`query_select()` runs a `SelectBuilder`. The generic `query_builder()` runs any builder via its `build()` output.

## Available builders

The client exposes a factory method for each builder.

<table>
    <thead>
        <tr>
            <th colspan="2" scope="col">Builder</th>
            <th colspan="2" scope="col">Factory</th>
            <th colspan="2" scope="col">Methods</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td colspan="2" scope="row" data-label="Builder"><code>SelectBuilder</code></td>
            <td colspan="2" scope="row" data-label="Factory"><code>select_builder(target)</code></td>
            <td colspan="2" scope="row" data-label="Methods"><code>fields</code>, <code>where_clause</code>, <code>order_by</code>, <code>limit</code>, <code>start</code>, <code>fetch</code></td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Builder"><code>CreateBuilder</code></td>
            <td colspan="2" scope="row" data-label="Factory"><code>create_builder(target)</code></td>
            <td colspan="2" scope="row" data-label="Methods"><code>content</code>, <code>set_field</code></td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Builder"><code>UpdateBuilder</code></td>
            <td colspan="2" scope="row" data-label="Factory"><code>update_builder(target)</code></td>
            <td colspan="2" scope="row" data-label="Methods"><code>content</code>, <code>merge</code>, <code>patch</code>, <code>replace</code>, <code>where_clause</code></td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Builder"><code>UpsertBuilder</code></td>
            <td colspan="2" scope="row" data-label="Factory"><code>upsert_builder(target)</code></td>
            <td colspan="2" scope="row" data-label="Methods"><code>content</code>, <code>merge</code></td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Builder"><code>DeleteBuilder</code></td>
            <td colspan="2" scope="row" data-label="Factory"><code>delete_builder(target)</code></td>
            <td colspan="2" scope="row" data-label="Methods"><code>where_clause</code></td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Builder"><code>InsertBuilder</code></td>
            <td colspan="2" scope="row" data-label="Factory"><code>insert_builder(table)</code></td>
            <td colspan="2" scope="row" data-label="Methods"><code>values</code>, <code>relation</code></td>
        </tr>
    </tbody>
</table>

## Examples

Build and inspect a statement without running it:

```python
var qb = client.select_builder("person")
    .fields("name, age")
    .where_clause("age >= 18")
    .limit(10)

print(qb.build())  # SELECT name, age FROM person WHERE age >= 18 LIMIT 10;
```

Create a record:

```python
var cb = client.create_builder("person").content('{ "name": "Chiru" }')
var resp = client.query(cb.build())
```

> [!NOTE]
> The older `QueryBuilder` is kept for backwards compatibility. New code should use the builders above.