Table

A Table holds the name of a table. Pass one as the target of a CRUD method to work on every record in the table, or as a query variable to name a table in SurrealQL. This page documents the class and the cases where it does something that a plain string does not.

from surrealdb import Table

Source: table.py

Constructor

Table(table_name)

A name that is not a str raises TypeError, so Table(None) fails at once rather than writing to a table that is named None.

table = Table("person")
print(table.table_name)

person

Properties

Tables and plain strings

A CRUD method reads a plain str target as a table name, so db.select("person") and db.select(Table("person")) do the same thing. A string is always a table name, even when it holds a :. To work on one record, pass a RecordID instead.

A plain string also works for a name that is not a simple identifier, such as audit-log, in select(), create(), update(), upsert() and delete(). insert() is the exception: it needs Table("audit-log"), and raises SurrealError for such a name given as a plain string.

from surrealdb import Surreal, Table

with Surreal("ws://localhost:8000") as db:
    db.signin({"username": "root", "password": "secret"})
    db.use("surrealdb", "docs")

    db.insert(Table("audit-log"), {"event": "signin"})
    print(len(db.select(Table("audit-log")).execute()))

1

On SurrealDB 3.0 and later, selecting from or deleting a table that does not exist raises NotFoundError. SurrealDB 2.x returns an empty list.

Tables in queries

Pass a Table as a query variable to name a table in SurrealQL. A str variable is a string value, not a table name, so SELECT * FROM $table with a str selects the string itself.

from surrealdb import RecordID, Surreal, Table

with Surreal("ws://localhost:8000") as db:
    db.signin({"username": "root", "password": "secret"})
    db.use("surrealdb", "docs")

    db.create(RecordID("person", "tobie"), {"name": "Tobie"})

    sql = "SELECT * FROM $table"
    print(db.query(sql, {"table": Table("person")}).first())
    print(db.query(sql, {"table": "person"}).first())

[{'id': RecordID(table_name=person, record_id='tobie'), 'name': 'Tobie'}]
['person']

A table that the server returns, for example from type::table("person"), reads back as a Table.

Text and equality

str() and repr() both give the table name, without escaping. Two Table values are equal when their names are equal, and a Table is never equal to a str. A Table is hashable, so it can be a dict key or a member of a set.

print(str(Table("person")))
print(Table("person") == Table("person"))
print(Table("person") == "person")

person
True
False

See also

• •

  Python values for every value class

• •

  RecordID for a target that names one record

• •

  Data manipulation for CRUD methods that take a table