# pyquickbase API reference: SchemaOperation

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), [Operation](https://matthew-williams-solutions.github.io/pyquickbase/reference/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).

A [`SchemaOperation`](https://matthew-williams-solutions.github.io/pyquickbase/reference/schema-operation/) is one schema operation offered to a model as a tool: `describe_schema`, `preview_schema_changes`, or `apply_schema_changes`. Get one from [`App.operation()`](https://matthew-williams-solutions.github.io/pyquickbase/reference/app/#operation). `apply_schema_changes` only runs with the confirmation `preview_schema_changes` returned for the same changes, while the schema is as it was.

The examples below use `plan`, 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:
    app = qb.app("bq1234567")
    plan = app.operation("preview_schema_changes")
```

Async:

```python
from pyquickbase import AsyncQuickbase

async with AsyncQuickbase(
    realm="acme", token="your_user_token"
) as qb:
    app = qb.app("bq1234567")
    plan = await app.operation("preview_schema_changes")
```

## What the methods return

| Type | What it is | Returned by |
|---|---|---|
| [`SchemaOperationName`](https://matthew-williams-solutions.github.io/pyquickbase/reference/tools/#SchemaOperationName) |  | [`name`](https://matthew-williams-solutions.github.io/pyquickbase/reference/schema-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/).

### `SchemaOperation.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
changes = plan.schema["properties"]["changes"]
kinds = [
    item["properties"]["action"]["const"]
    for item in changes["items"]["oneOf"]
]
print(kinds[:3])
```

Async example:

```python
changes = plan.schema["properties"]["changes"]
kinds = [
    item["properties"]["action"]["const"]
    for item in changes["items"]["oneOf"]
]
print(kinds[:3])
```

Output:

```text
['create_table', 'update_table', 'delete_table']
```

### `SchemaOperation.name`

What the operation does, such as `preview_schema_changes`.

```python
name: SchemaOperationName
```

Sync example:

```python
print(plan.name)
```

Async example:

```python
print(plan.name)
```

Output:

```text
preview_schema_changes
```

## Run it

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

### `SchemaOperation.run()`

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

```python
run(arguments: Mapping[str, Any]) -> Any
```

**Parameters**

- **`arguments`** `Mapping[str, Any]`, required  
  The arguments from the model's tool call.

**Returns** `Any`

For `describe_schema`, a list of [`TableSchema`](https://matthew-williams-solutions.github.io/pyquickbase/reference/metadata/#TableSchema). For `preview_schema_changes`, a [`SchemaPlan`](https://matthew-williams-solutions.github.io/pyquickbase/reference/schema-changes/#SchemaPlan), whose `confirmation` `apply_schema_changes` needs, unless the plan has blockers or changes nothing. For `apply_schema_changes`, a [`SchemaChangeResult`](https://matthew-williams-solutions.github.io/pyquickbase/reference/schema-changes/#SchemaChangeResult). [`tool_result`](https://matthew-williams-solutions.github.io/pyquickbase/reference/tools/#tool_result) takes each.

**Raises**

- [`InvalidValueError`](https://matthew-williams-solutions.github.io/pyquickbase/reference/errors/#InvalidValueError): An argument can't be used. Nothing was sent.
- [`QueryError`](https://matthew-williams-solutions.github.io/pyquickbase/reference/errors/#QueryError): `apply_schema_changes` has no confirmation, or one that doesn't match these changes and the schema as it is now. Nothing was changed.
- [`SchemaChangeError`](https://matthew-williams-solutions.github.io/pyquickbase/reference/errors/#SchemaChangeError): A change failed while applying. Its `result` says which were made.

Sync example:

```python
from pyquickbase import tool_result

change = {
    "action": "create_field",
    "table": "Job Tasks",
    "label": "Crew",
    "type": "text",
}
result = tool_result(plan.run({"changes": [change]}))
print(result["changes"][0]["summary"])
print("confirmation" in result)
```

Async example:

```python
from pyquickbase import tool_result

change = {
    "action": "create_field",
    "table": "Job Tasks",
    "label": "Crew",
    "type": "text",
}
result = tool_result(await plan.run({"changes": [change]}))
print(result["changes"][0]["summary"])
print("confirmation" in result)
```

Output:

```text
Add field "Crew" (text) to Job Tasks.
True
```