# pyquickbase API reference: Operation

This describes version 1.0.0rc13. Other pages: [Quickbase](https://matthew-williams-solutions.github.io/pyquickbase/reference/quickbase.txt), [App](https://matthew-williams-solutions.github.io/pyquickbase/reference/app.txt), [Table](https://matthew-williams-solutions.github.io/pyquickbase/reference/table.txt), [Report](https://matthew-williams-solutions.github.io/pyquickbase/reference/report.txt), [SchemaOperation](https://matthew-williams-solutions.github.io/pyquickbase/reference/schema-operation.txt), [Queries](https://matthew-williams-solutions.github.io/pyquickbase/reference/queries.txt), [Records and results](https://matthew-williams-solutions.github.io/pyquickbase/reference/records.txt), [Metadata](https://matthew-williams-solutions.github.io/pyquickbase/reference/metadata.txt), [Schema changes](https://matthew-williams-solutions.github.io/pyquickbase/reference/schema-changes.txt), [Policies](https://matthew-williams-solutions.github.io/pyquickbase/reference/policies.txt), [Rules](https://matthew-williams-solutions.github.io/pyquickbase/reference/rules.txt), [Retries](https://matthew-williams-solutions.github.io/pyquickbase/reference/retries.txt), [Tools for models](https://matthew-williams-solutions.github.io/pyquickbase/reference/tools.txt), [Errors](https://matthew-williams-solutions.github.io/pyquickbase/reference/errors.txt).

An [`Operation`](https://matthew-williams-solutions.github.io/pyquickbase/reference/operation/) is one table operation offered to a model as a tool: a JSON Schema of the arguments it may send, and `run()`, which checks them against the same lists before calling the table. Get one from [`Table.operation()`](https://matthew-williams-solutions.github.io/pyquickbase/reference/table/#operation).

The examples below use `search`, made as shown here. `Job Tasks` has `Title`, `Status`, `Hours`, `Due Date`, `Code`, which is unique, and `Attachment`. It starts with three records, and each example starts from those again. A live test runs every example with both clients and checks its output.

Sync:

```python
from pyquickbase import Quickbase

with Quickbase(
    realm="acme", token="your_user_token"
) as qb:
    tasks = qb.app("bq1234567").table("Job Tasks")
    search = tasks.operation(
        "query", fields=["Title", "Status"]
    )
```

Async:

```python
from pyquickbase import AsyncQuickbase

async with AsyncQuickbase(
    realm="acme", token="your_user_token"
) as qb:
    tasks = qb.app("bq1234567").table("Job Tasks")
    search = await tasks.operation(
        "query", fields=["Title", "Status"]
    )
```

## What the methods return

| Type | What it is | Returned by |
|---|---|---|
| [`OperationName`](https://matthew-williams-solutions.github.io/pyquickbase/reference/tools/#OperationName) |  | [`name`](https://matthew-williams-solutions.github.io/pyquickbase/reference/operation/#name) |

## Describe it to a model

For the full picture, see [Using pyquickbase from an AI agent](https://matthew-williams-solutions.github.io/pyquickbase/agents/).

### `Operation.schema`

The JSON Schema of the arguments a model may send, for a tool's input.

It's self-contained, with no `$ref`, and a new dictionary each time, so you can add to it.

```python
schema: dict[str, Any]
```

Sync example:

```python
print(sorted(search.schema["properties"]))
select = search.schema["properties"]["select"]
print(select["items"]["enum"])
```

Async example:

```python
print(sorted(search.schema["properties"]))
select = search.schema["properties"]["select"]
print(select["items"]["enum"])
```

Output:

```text
['limit', 'order_by', 'select', 'skip', 'where']
['Title', 'Status']
```

### `Operation.name`

What the operation does, such as `query`.

```python
name: OperationName
```

Sync example:

```python
print(search.name)
```

Async example:

```python
print(search.name)
```

Output:

```text
query
```

## Run it

For the full picture, see [Using pyquickbase from an AI agent](https://matthew-williams-solutions.github.io/pyquickbase/agents/).

### `Operation.run()`

Check a model's arguments, and run the operation.

Arguments the schema doesn't allow are refused before anything is sent, with a message that says where the mistake is, and doesn't repeat the values sent. Spellings models tend to write for a closed value are read as the one they mean, such as `sort` for `order_by`, `"order": "DESC"` for `"direction": "desc"`, and `starts with` for `starts_with`. Labels must match exactly.

```python
run(
    arguments: Mapping[str, Any],
    *,
    scope: Expression | None = None,
) -> Any
```

**Parameters**

- **`arguments`** `Mapping[str, Any]`, required  
  The arguments from the model's tool call.
- **`scope`** `Expression | None`, optional  
  A condition your code fixes, such as the user's project, that every record must match. It's added to every filter. An operation that names records, such as `update`, first checks that they all match it. A write can't set a field the scope uses, and `insert` fills those fields in from the scope, which must then be only `==` conditions joined with `&`. A report can't take one.

**Returns** `Any`

What the table method returns, such as a [`Page`](https://matthew-williams-solutions.github.io/pyquickbase/reference/records/#Page) for `query`, which [`tool_result`](https://matthew-williams-solutions.github.io/pyquickbase/reference/tools/#tool_result) takes.

**Raises**

- [`QueryError`](https://matthew-williams-solutions.github.io/pyquickbase/reference/errors/#QueryError): An argument can't be used, a record named isn't in `scope`, a write sets a field the scope uses, or a delete matches more than `max_records_per_call`. Nothing was sent, other than the query that checks the scope or counts a delete.
- [`InvalidValueError`](https://matthew-williams-solutions.github.io/pyquickbase/reference/errors/#InvalidValueError): A record or value can't be written. Nothing was sent.

Sync example:

```python
page = search.run(
    {
        "where": {
            "field": "Status",
            "op": "==",
            "value": "Open",
        },
        "select": ["Title"],
        "limit": 5,
    }
)
print([task["Title"] for task in page.records])
```

Async example:

```python
page = await search.run(
    {
        "where": {
            "field": "Status",
            "op": "==",
            "value": "Open",
        },
        "select": ["Title"],
        "limit": 5,
    }
)
print([task["Title"] for task in page.records])
```

Output:

```text
['Pour slab', 'Frame walls']
```