Skip to content

Markdown

Operation

An 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().

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.

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"]
    )

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"]
    )

Describe it to a model

For the full picture, see Using pyquickbase from an AI agent.

The arguments' JSON 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.

schema: dict[str, Any]

Example

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

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

Output

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

The operation's name

What the operation does, such as query.

name: OperationName

Example

print(search.name)

print(search.name)

Output

query

Run it

For the full picture, see Using pyquickbase from an AI agent.

Run an operation

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.

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 for query, which tool_result takes.

Raises

  • 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: A record or value can't be written. Nothing was sent.
run(
    arguments: Mapping[str, Any],
    *,
    scope: Expression | None = None,
) -> Any

Example

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

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

Output

['Pour slab', 'Frame walls']