# Executing queries

Learn how to run SurrealQL with the Mojo SDK, use the CRUD convenience methods, and read responses.

The primary way to run SurrealQL with the Mojo SDK is `query()`, which sends one or more statements and returns an `RpcResponse`.

```python
var resp = client.query("SELECT * FROM person WHERE age > 18;")
```

## Reading the response

Every call returns an `RpcResponse`. Check `is_ok()` before reading the result. The decoded text representation is available on `result`, and the raw bytes on `result_raw`.

```python
if resp.is_ok():
    # CBOR-decoded text representation for convenience
    if resp.result:
        print(resp.result.value())
    # Raw CBOR bytes if you need them
    print("bytes:", len(resp.result_raw))
else:
    print("code:", resp.error_code().value())
    print("message:", resp.error_message().value())
```

`RpcResponse` exposes the following:

<table>
    <thead>
        <tr>
            <th colspan="2" scope="col">Member</th>
            <th colspan="2" scope="col">Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td colspan="2" scope="row" data-label="Member"><code>is_ok()</code></td>
            <td colspan="2" scope="row" data-label="Description">Returns <code>True</code> when there is no error.</td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Member"><code>is_error()</code></td>
            <td colspan="2" scope="row" data-label="Description">Returns <code>True</code> when the response carries an error.</td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Member"><code>has_result()</code></td>
            <td colspan="2" scope="row" data-label="Description">Returns <code>True</code> when a result is present.</td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Member"><code>result</code></td>
            <td colspan="2" scope="row" data-label="Description">The decoded text representation, as <code>Optional[String]</code>.</td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Member"><code>result_raw</code></td>
            <td colspan="2" scope="row" data-label="Description">The raw CBOR or JSON bytes, as <code>List[UInt8]</code>.</td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Member"><code>error_message()</code></td>
            <td colspan="2" scope="row" data-label="Description">The error message, as <code>Optional[String]</code>.</td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Member"><code>error_code()</code></td>
            <td colspan="2" scope="row" data-label="Description">The error code, as <code>Optional[Int]</code>.</td>
        </tr>
    </tbody>
</table>

## Convenience methods

The SDK wraps the most common statements so you do not have to write the SurrealQL by hand. Each takes the table or record to act on and a JSON document.

```python
client.create("person", '{ "name": "Chiru", "age": 30 }')
client.select("person:chiru")
client.update("person:chiru", '{ "age": 31 }')
client.delete("person:chiru")
client.insert("person", '[{ "name": "Alice" }, { "name": "Bob" }]')
```

These build a SurrealQL statement under the hood. For example, `create("person", data)` runs `CREATE person CONTENT <data>;`. See the method reference for the full list, including [`upsert`](/docs/reference/mojo/methods/upsert.md), [`merge`](/docs/reference/mojo/methods/merge.md), [`patch`](/docs/reference/mojo/methods/patch.md), and [`insert_relation`](/docs/reference/mojo/methods/insert-relation.md).

## Bindings

`query()` accepts a `bindings_json` argument.

```python
var resp = client.query("SELECT * FROM person;", "{}")
```

> [!NOTE]
> A dedicated API for passing arbitrary CBOR bindings is on the roadmap. Today, CBOR connections support the default `"{}"`, while JSON-RPC connections accept raw JSON strings via `bindings_json`.

## Sessions and transactions

Each `query` is wrapped in its own implicit transaction by the server. To run several statements atomically, use [`transaction_multi`](/docs/reference/mojo/methods/transaction-multi.md), or the [transactions](/docs/reference/mojo/concepts/transactions.md) concept page for the full picture.