Tablas y esquemas

Nexus guarda sus datos en tablas, en el formato abierto Apache Iceberg, agrupadas en esquemas. El esquema default siempre existe y se usa salvo que pase schema=. Esta página cubre nexus.tables y nexus.schemas.

Antes de empezarCopiar el enlace

• Leer tablas requiere acceso de lectura. Crear tablas y cambiar columnas requiere una clave cuyo Acceso incluya cambios de esquema.
• Todos los ejemplos suponen nexus = Nexus.connect().

EsquemasCopiar el enlace

for schema in nexus.schemas.list():   # the default schema first
    print(schema)

nexus.schemas.create("finance")
print(nexus.schemas.describe("finance"))
nexus.schemas.delete("finance")       # only when it holds no tables and no files

Encuentre y describa tablasCopiar el enlace

for table in nexus.tables.list(search="order"):
    print(table["name"], table["column_count"], table["doc"])

details = nexus.tables.describe("orders")

list() recorre todas las páginas por usted. Cada entrada tiene name, schema, owner, doc, column_count, about, made_by y mine. Pase el ID de un proyecto en made_by= para filtrar.

Cree una tablaCopiar el enlace

from klarety import Nexus, RefusedError

with Nexus.connect() as nexus:
    try:
        created = nexus.tables.create(
            "orders",
            [
                {"name": "order_id", "type": "string", "doc": "Order number."},
                {"name": "customer", "type": "string", "doc": "Customer name."},
                {"name": "amount", "type": "double", "doc": "Order total in US dollars."},
                {"name": "ordered_at", "type": "timestamp", "doc": "When the order was placed."},
            ],
            doc="One row per customer order.",
            identifier_columns=["order_id"],
            expectations=[{"column": "amount", "rule": "range", "minimum": 0}],
        )
    except RefusedError as refused:
        raise SystemExit(f"Could not create the table: {refused}")
    print(created)

• doc es obligatorio, en la tabla y en cada columna: una línea que diga qué contiene. Una columna también puede definir "required": True.
• identifier_columns nombra las columnas que identifican una fila (su clave).
• expectations son reglas que revisa cada carga; las filas que las incumplen se apartan bajo el nombre de la regla.
• relationships (por ejemplo {"columns": ["customer"], "references": "customers", "referenced_columns": ["id"]}) ayudan a Nexus a organizar ambas tablas. No se exigen al escribir.
• Nexus elige la organización física y la informa. cluster_by sugiere las columnas por las que más filtra; pin_layout() evita que cambie a medida que crece la tabla.

Normalmente no necesita create(): cargar un archivo crea su tabla.

Describa qué significa una tablaCopiar el enlace

nexus.tables.describe_meaning(
    "orders", grain="one order", time_column="ordered_at", status="ready"
)
nexus.tables.set_column_doc("orders", "amount", "Order total in US dollars, tax included.")

status es draft, ready o deprecated. Solo cambian los valores que pase. Las personas y la IA leen estas descripciones para entender sus datos.

Lea filasCopiar el enlace

for row in nexus.tables.rows("orders", where=["customer:eq:Acme"], order_by="ordered_at"):
    print(row)

rows() pagina a medida que recorre. Un filtro where es columna:op:valor, donde op es eq, ne, gt, ge, lt, le, in, contains, is_null o not_null. Para traer muchas filas por clave en una lectura, use in: "order_id:in:A1,A2,A3". Para algo más, use SQL.

Edite unas pocas filasCopiar el enlace

edit_rows() agrega, actualiza y borra hasta 500 filas en un solo commit:

from klarety import ConflictError

try:
    nexus.tables.edit_rows(
        "orders",
        added=[{"order_id": "A9", "customer": "Acme", "amount": "120.00"}],
        updated=[{"row": {"order_id": "A1", "amount": "80.00"}, "values": {"amount": "85.00"}}],
        write_id="fix-a1-2026-11-10",
    )
except ConflictError as changed:
    print("A row changed since you read it:", changed)

• En updated, row es la fila como usted la leyó y values los valores nuevos, escritos como texto. Si algún valor de row ya no coincide con lo guardado, no se guarda nada y ConflictError nombra cada fila que cambió.
• write_id nombra la escritura (de 8 a 64 letras, dígitos, - o _). Tras un tiempo de espera agotado, reenvíe con el mismo write_id: una escritura que ya llegó se responde como guardada, nunca se hace dos veces.
• Para más de 500 filas, cargue un archivo con mode="upsert".

Cambie columnasCopiar el enlace

nexus.tables.add_column("orders", {"name": "channel", "type": "string", "doc": "Where the order came from."})
nexus.tables.change_columns("orders", rename={"channel": "sales_channel"}, retype={"amount": "decimal(12,2)"})
nexus.tables.change_columns("orders", remove=["sales_channel"])
nexus.tables.restore_column("orders", "sales_channel")

Todos los cambios de una llamada a change_columns() ocurren juntos. Una columna eliminada se conserva hasta que se purga, así que restore_column() puede traerla de vuelta.

Historial, reversión y restauraciónCopiar el enlace

Cada cambio crea una instantánea de la tabla.

history = nexus.tables.snapshots("orders")
nexus.tables.rollback("orders", snapshot_id=1234567890)

new_rows = nexus.tables.changes("orders", since=0)   # pass back "through" next time

delete() elimina una tabla, que sigue restaurable durante el periodo de recuperación de su plan:

nexus.tables.delete("orders")
print(nexus.tables.deleted())
nexus.tables.restore("orders")

Revise calidad y actividadCopiar el enlace

print(nexus.tables.quality("orders"))
print(nexus.tables.authors("orders", days=7))   # who added and changed rows, day by day
print(nexus.tables.lineage("orders"))

Qué puede salir malCopiar el enlace

Próximos pasosCopiar el enlace

• Cargar datos para llenar tablas desde archivos.
• Ejecutar SQL para consultarlas.
• Trabajos y trabajos por lotes para cambiar muchas filas con SQL.