Markdown

Metadata

These describe an app and what's in it. The client caches them for five minutes by default, and each holds everything Quickbase returned in raw.

The examples below use tasks, made as shown here, and app, which is qb.app("bq1234567"). 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. projects is a table named Job Projects, with a Name field.

SyncAsync

from pyquickbase import Quickbase

with Quickbase(
    realm="acme", token="your_user_token"
) as qb:
    tasks = qb.app("bq1234567").table("Job Tasks")

from pyquickbase import AsyncQuickbase

async with AsyncQuickbase(
    realm="acme", token="your_user_token"
) as qb:
    tasks = qb.app("bq1234567").table("Job Tasks")

Apps

For the full picture, see Reading records.

AppInfo

An app's metadata.

Attributes

• id str
  The app's ID.
• name str
  The app's name.
• description str
  The app's description, which may be empty.
• time_zone str | None
  The app's time zone, such as (UTC) Coordinated Universal Time, if reported.
• date_format str | None
  How the app writes dates, such as MM-DD-YYYY, if reported.
• raw Mapping[str, Any]
  Everything Quickbase returned, for anything not listed here.

Example

SyncAsync

info = app.info()
print(info.id)

info = await app.info()
print(info.id)

Output

bq1234567

Role

A role in an app.

Attributes

• id int
  The role's ID.
• name str
  The role's name.
• access str
  Quickbase's name for its level, such as Basic Access.
• raw Mapping[str, Any]
  Everything Quickbase returned, for anything not listed here.

Example

SyncAsync

for role in app.roles():
    if role.name == "Administrator":
        print(role.name, role.access)

for role in await app.roles():
    if role.name == "Administrator":
        print(role.name, role.access)

Output

Administrator Administrator

AppEvent

Something in an app that runs when records change or on a schedule, such as a webhook.

Quickbase lists webhooks, Quickbase actions, email notifications, subscriptions, reminders, and automations that records trigger. It leaves out scheduled automations, and doesn't say which changes set each one off.

Attributes

• type str
webhook, qb-action, email-notification, subscription, reminder, or automation.
• name str | None
  Its name. Quickbase doesn't name automations, so it's None for those.
• active bool
  Whether it's switched on.
• table_id str | None
  The table it watches, if Quickbase said.
• url str | None
  For an automation, a link to it in Quickbase.
• owner User | None
  Who owns it, or None if the client's policy leaves it out.
• raw Mapping[str, Any]
  Everything Quickbase returned, for anything not listed here.
• runs_on_changes bool
  Whether a change to records can set it off. Subscriptions and reminders run on a schedule instead.

Example

SyncAsync

for event in tasks.events():
    if event.active and event.runs_on_changes:
        print(event.type, event.name or event.url)

for event in await tasks.events():
    if event.active and event.runs_on_changes:
        print(event.type, event.name or event.url)

Tables and reports

For the full picture, see Reading records.

TableInfo

A table's metadata.

Attributes

• id str
  The table's ID.
• name str
  The table's name.
• description str
  The table's description, which may be empty.
• key_field_id int | None
  The ID of the table's key field, which is 3, Record ID#, unless someone changed it in the Quickbase interface. None if Quickbase left it out.
• raw Mapping[str, Any]
  Everything Quickbase returned, for anything not listed here.

Example

SyncAsync

info = tasks.info()
print(info.name, info.key_field_id)

info = await tasks.info()
print(info.name, info.key_field_id)

Output

Job Tasks 3

ReportInfo

A report's metadata.

Attributes

• id str
  The report's ID.
• name str
  The report's name.
• type str
table, summary, chart, or another Quickbase type.
• description str
  The report's description, which may be empty.
• incomplete bool
  Whether Quickbase can't run the report through the API, as with one that asks the user for a value.
• raw Mapping[str, Any]
  Everything Quickbase returned, for anything not listed here.

Example

SyncAsync

reports = tasks.reports()
first = reports[0]
print(first.name, first.type, first.incomplete)

reports = await tasks.reports()
first = reports[0]
print(first.name, first.type, first.incomplete)

Output

List All table False

Fields and relationships

For the full picture, see Changing the schema.

Field

A field's metadata.

Attributes

• id int
  The field's ID.
• label str
  The field's label.
• type str
  Quickbase's name for the field's type, such as text or numeric.
• mode str | None
formula, lookup, summary, or None for a plain field.
• required bool
  Whether the field must have a value.
• unique bool
  Whether values must be different on every record.
• appears_by_default bool
  Whether a query returns the field when select is left out.
• choices tuple[str, ...]
  The options of a multiple-choice field, or empty for other fields.
• allow_new_choices bool
  Quickbase's allowNewChoices setting, or False if it isn't reported.
• formula str | None
  The formula's text, or None if the field doesn't have one.
• help_text str
  The help Quickbase shows beside the field on forms, which may be empty.
• decimal_places int | None
  Only how a number is displayed: Quickbase still stores 1.5 in a field set to 0 places.
• is_foreign_key bool
  Whether the field links to a parent table's record.
• lookup_reference_field_id int | None
  For a lookup, the foreign key field on this table.
• lookup_target_field_id int | None
  For a lookup, the field it reads on the parent.
• summary_reference_field_id int | None
  For a summary, the foreign key field on the child table.
• summary_target_field_id int | None
  For a summary, the field it reads on the child.
• summary_function str | None
  For a summary, Quickbase's name for its calculation, such as SUM.
• summary_query str | None
  For a summary, the filter on which child records it combines, such as {7.EX.true}, or None for all of them. On a client with a policy it's None unless the client can read every field the filter uses on the child table.
• raw Mapping[str, Any]
  Everything Quickbase returned, for anything not listed here.

Example

SyncAsync

for field in tasks.fields():
    if field.label == "Status":
        print(field.id, field.type, field.mode)
        print(sorted(field.choices), field.required)

for field in await tasks.fields():
    if field.label == "Status":
        print(field.id, field.type, field.mode)
        print(sorted(field.choices), field.required)

Output

7 text-multiple-choice None
['Done', 'Open'] False

FieldUsage

Where a field is used in its app, as counted on the field's Usage page in Quickbase.

Quickbase counts a field in the reports it makes for every table, so most fields have a few uses. Counts can take a few seconds to include a change.

Attributes

• field_id int
  The field's ID.
• label str
  The field's label.
• counts Mapping[str, int]
  How many of each kind of thing use it, such as {"reports": 2, "forms": 1}, leaving out the kinds that don't. A kind Quickbase adds later is included too.
• raw Mapping[str, Any]
  Everything Quickbase returned, for anything not listed here.
• total int
  How many things use the field in all.

Example

SyncAsync

[usage] = tasks.field_usage("Title")
print(usage.field_id, usage.label)
print(usage.counts["default_reports"], usage.total > 0)
print("report" in usage.describe())

[usage] = await tasks.field_usage("Title")
print(usage.field_id, usage.label)
print(usage.counts["default_reports"], usage.total > 0)
print("report" in usage.describe())

Output

6 Title
1 True
True

Describe a field's uses in words

The uses in words, most first, such as 2 reports and 1 form, or nothing.

Returns str

describe() -> str

Relationship

A parent-child link between two tables.

create_relationship() and ensure_lookup_field() take the parent's field to look up, which isn't what lookup_field_ids holds.

Attributes

• id int
  The relationship's ID.
• parent_table_id str
  The parent table's ID.
• child_table_id str
  The child table's ID.
• foreign_key_field_id int | None
  The child's field that holds the parent's Record ID#, if reported.
• lookup_field_ids tuple[int, ...]
  The lookup fields, which are on the child.
• summary_field_ids tuple[int, ...]
  The summary fields, which are on the parent.
• is_cross_app bool
  Whether Quickbase reports the parent as being in another app.
• raw Mapping[str, Any]
  Everything Quickbase returned, for anything not listed here.

Example

SyncAsync

relationship = tasks.ensure_relationship(
    projects, foreign_key="Project"
)
print(relationship.foreign_key_field_id)
print(
    relationship.lookup_field_ids, relationship.is_cross_app
)

relationship = await tasks.ensure_relationship(
    projects, foreign_key="Project"
)
print(relationship.foreign_key_field_id)
print(
    relationship.lookup_field_ids, relationship.is_cross_app
)

Output

12
() False

TableSchema

A table's fields and the relationships in which it's the child, as the client can see them.

Attributes

• info TableInfo
  The table's details.
• fields tuple[Field, ...]
  Its fields.
• relationships tuple[Relationship, ...]
  The relationships in which it's the child.

Example

SyncAsync

describe = app.operation("describe_schema")
(schema,) = describe.run({"tables": ["Job Tasks"]})
print(schema.info.name, len(schema.fields))

describe = await app.operation("describe_schema")
(schema,) = await describe.run({"tables": ["Job Tasks"]})
print(schema.info.name, len(schema.fields))

Output

Job Tasks 11