Referencia del DSL¶

Todo lo que exporta from tai_sql import *. Es la superficie de contrato con tus schemas: los cambios son aditivos o pasan por una deprecación explícita.

Cabecera del schema¶

datasource(
    provider,                        # env() | connection_string() | params()
    schema='public',
    syntax='v1',                     # 'v1' | 'v2'  (las plantillas nuevas usan v2)
    operative_fields=False,
    secret_key_name='SECRET_KEY',
    default_vector_dimensions=384,
    # Del cliente generado (su hogar es PythonClientGenerator):
    sqlalchemy_logs=False, pool_pre_ping=True, pool_recycle=3600,
    pool_size=5, max_overflow=5, pool_timeout=30, ssl=True,
    # Backup:
    backup_storage=None, backup_format='custom', backup_retention=None,
    restore_provider=None,
)

generate(*generadores)

query('fichero.sql')                 # lee views/<schema>/fichero.sql

Providers¶

env('MAIN_DATABASE_URL')
connection_string('postgresql://u:p@h:5432/db')
params(host, database, username, password, port=5432, driver='postgresql', query={})

Columnas¶

column(
    primary_key=False,
    unique=False,
    default=None,
    server_now=False,
    index=False,
    autoincrement=False,
    encrypt=False,
    description='',
    self_reference=None,
)

vector_column(
    dimensions=None,
    source=None,
    encoder=None,
    metric='cosine',                 # 'cosine' | 'l2' | 'inner_product'
    threshold=None,
    index=False,
    description='',
)

Relaciones y constraints¶

relation(fields, references, backref, onDelete='cascade', onUpdate='cascade')

unique_constraint(*columns)
index_constraint(*columns, unique=False, method=None)

Anotaciones¶

v2v1

col[T]              # una columna de tipo T; col[T | None] si es opcional
onetomany[Modelo]   # lado implícito de una relación 1:N
manytoone[Modelo]   # lado que posee la FK
onetoone[Modelo]    # relación 1:1

T                   # una columna; Optional[T] si es opcional
List[Modelo]        # lado implícito de una relación 1:N
Modelo              # lado que posee la FK

Clases base¶

Table               # una tabla
View                # una vista: __query__ + columnas declaradas
Enum                # un enumerado

Triggers¶

@on_create(timing='before', priority=1, when=None)
@on_update(timing='before', priority=1, fields=None, when=None)
@on_delete(timing='before', priority=1, when=None)

TriggerAPI[Modelo]   # el type hint del parámetro t

Columnas calculadas¶

def nombre(self) -> col[T]: ...      # v2, sin decorador

@calculated_column                   # v1, o si prefieres ser explícito
def nombre(self) -> T: ...

Encoders¶

SentenceTransformerEncoder(model='all-MiniLM-L6-v2', dimensions=None)
OpenAIEncoder(model='text-embedding-3-small', dimensions=None)
AzureOpenAIEncoder(model='text-embedding-3-small', dimensions=None,
                   azure_endpoint=None, api_version=None)
GoogleEncoder(model='gemini-embedding-2-preview', dimensions=None, location=None)

Tipos y extensión¶

get_type_registry()
register_type(descriptor)
TypeDescriptor        # la ABC para un tipo propio
BaseEncoder           # la ABC para un encoder propio

Re-exports de conveniencia¶

Existen porque los schemas usan from tai_sql import *:

List, Optional, datetime, date, time, bigint, text, numeric, largebinary, vector

Dunders reconocidos¶

Dunder	Dónde	Para qué
`__tablename__`	Table, View	Nombre físico. Obligatorio
`__description__`	Table, View	Descripción, si no usas el docstring
`__examples__`	Table, View	Ejemplos de fila
`__constraints__`	Table	UNIQUE e índices de varias columnas
`__operative_fields__`	Table	Fuerza las columnas de auditoría
`__query__`	View	El SQL que la define
`__is_view__`	View	Marcador interno

Y en el cuerpo de una View: materialized = True y dependencies = [...].