db.models — Phoenix API Reference 4.6.3 documentation

class Base(**kwargs: Any)#

Bases: DeclarativeBase

metadata: ClassVar[MetaData] = MetaData()#: Refers to the _schema.MetaData collection that will be used for new _schema.Table objects.

See also

orm_declarative_metadata

registry: ClassVar[_RegistryType] = <sqlalchemy.orm.decl_api.registry object>#: Refers to the _orm.registry in use where new _orm.Mapper objects will be associated.

type_annotation_map = {<class 'db.models.ExperimentRunOutput'>: <class 'db.models.JsonDict'>, typing.Dict[str, typing.Any]: <class 'db.models.JsonDict'>, typing.List[typing.Dict[str, typing.Any]]: <class 'db.models.JsonList'>}#

class Dataset(**kwargs)#

Bases: Base

created_at: Mapped[datetime]#

description: Mapped[str | None]#

example_count#

id: Mapped[int]#

async load_example_count(session: AsyncSession) → None#

metadata_: Mapped[Dict[str, Any]]#

name: Mapped[str]#

updated_at: Mapped[datetime]#

class DatasetExample(**kwargs)#

Bases: Base

created_at: Mapped[datetime]#

dataset_id: Mapped[int]#

id: Mapped[int]#

span: Mapped[Span | None]#

span_rowid: Mapped[int | None]#

class DatasetExampleRevision(**kwargs)#

Bases: Base

created_at: Mapped[datetime]#

dataset_example_id: Mapped[int]#

dataset_version_id: Mapped[int]#

id: Mapped[int]#

input: Mapped[Dict[str, Any]]#

metadata_: Mapped[Dict[str, Any]]#

output: Mapped[Dict[str, Any]]#

revision_kind: Mapped[str]#

class DatasetVersion(**kwargs)#

Bases: Base

created_at: Mapped[datetime]#

dataset_id: Mapped[int]#

description: Mapped[str | None]#

id: Mapped[int]#

metadata_: Mapped[Dict[str, Any]]#

class DocumentAnnotation(**kwargs)#

Bases: Base

annotator_kind: Mapped[str]#

created_at: Mapped[datetime]#

document_position: Mapped[int]#

explanation: Mapped[str | None]#

id: Mapped[int]#

label: Mapped[str | None]#

metadata_: Mapped[Dict[str, Any]]#

name: Mapped[str]#

score: Mapped[float | None]#

span: Mapped[Span]#

span_rowid: Mapped[int]#

updated_at: Mapped[datetime]#

class Experiment(**kwargs)#

Bases: Base

created_at: Mapped[datetime]#

dataset_id: Mapped[int]#

dataset_version_id: Mapped[int]#

description: Mapped[str | None]#

id: Mapped[int]#

metadata_: Mapped[Dict[str, Any]]#

name: Mapped[str]#

project_name: Mapped[str | None]#

repetitions: Mapped[int]#

updated_at: Mapped[datetime]#

class ExperimentRun(**kwargs)#

Bases: Base

completion_token_count: Mapped[int | None]#

dataset_example_id: Mapped[int]#

end_time: Mapped[datetime]#

error: Mapped[str | None]#

experiment_id: Mapped[int]#

id: Mapped[int]#

output: Mapped[ExperimentRunOutput]#

prompt_token_count: Mapped[int | None]#

repetition_number: Mapped[int]#

start_time: Mapped[datetime]#

trace: Mapped[Trace]#

trace_id: Mapped[str | None]#

class ExperimentRunAnnotation(**kwargs)#

Bases: Base

annotator_kind: Mapped[str]#

end_time: Mapped[datetime]#

error: Mapped[str | None]#

experiment_run_id: Mapped[int]#

explanation: Mapped[str | None]#

id: Mapped[int]#

label: Mapped[str | None]#

metadata_: Mapped[Dict[str, Any]]#

name: Mapped[str]#

score: Mapped[float | None]#

start_time: Mapped[datetime]#

trace_id: Mapped[str | None]#

class ExperimentRunOutput#

Bases: TypedDict

task_output: Any#

class JSONB(none_as_null: bool = False)#

Bases: JSON

class JsonDict(*args: Any, **kwargs: Any)#

Bases: TypeDecorator

cache_ok: bool | None = True#

Indicate if statements using this ExternalType are “safe to cache”.

The default value None will emit a warning and then not allow caching of a statement which includes this type. Set to False to disable statements using this type from being cached at all without a warning. When set to True, the object’s class and selected elements from its state will be used as part of the cache key. For example, using a TypeDecorator:

class MyType(TypeDecorator):
    impl = String

    cache_ok = True

    def __init__(self, choices):
        self.choices = tuple(choices)
        self.internal_only = True

The cache key for the above type would be equivalent to:

>>> MyType(["a", "b", "c"])._static_cache_key
(<class '__main__.MyType'>, ('choices', ('a', 'b', 'c')))

The caching scheme will extract attributes from the type that correspond to the names of parameters in the __init__() method. Above, the “choices” attribute becomes part of the cache key but “internal_only” does not, because there is no parameter named “internal_only”.

The requirements for cacheable elements is that they are hashable and also that they indicate the same SQL rendered for expressions using this type every time for a given cache value.

To accommodate for datatypes that refer to unhashable structures such as dictionaries, sets and lists, these objects can be made “cacheable” by assigning hashable structures to the attributes whose names correspond with the names of the arguments. For example, a datatype which accepts a dictionary of lookup values may publish this as a sorted series of tuples. Given a previously un-cacheable type as:

class LookupType(UserDefinedType):
    """a custom type that accepts a dictionary as a parameter.

    this is the non-cacheable version, as "self.lookup" is not
    hashable.

    """

    def __init__(self, lookup):
        self.lookup = lookup

    def get_col_spec(self, **kw):
        return "VARCHAR(255)"

    def bind_processor(self, dialect): ...  # works with "self.lookup" ...

Where “lookup” is a dictionary. The type will not be able to generate a cache key:

>>> type_ = LookupType({"a": 10, "b": 20})
>>> type_._static_cache_key
<stdin>:1: SAWarning: UserDefinedType LookupType({'a': 10, 'b': 20}) will not
produce a cache key because the ``cache_ok`` flag is not set to True.
Set this flag to True if this type object's state is safe to use
in a cache key, or False to disable this warning.
symbol('no_cache')

If we did set up such a cache key, it wouldn’t be usable. We would get a tuple structure that contains a dictionary inside of it, which cannot itself be used as a key in a “cache dictionary” such as SQLAlchemy’s statement cache, since Python dictionaries aren’t hashable:

>>> # set cache_ok = True
>>> type_.cache_ok = True

>>> # this is the cache key it would generate
>>> key = type_._static_cache_key
>>> key
(<class '__main__.LookupType'>, ('lookup', {'a': 10, 'b': 20}))

>>> # however this key is not hashable, will fail when used with
>>> # SQLAlchemy statement cache
>>> some_cache = {key: "some sql value"}
Traceback (most recent call last): File "<stdin>", line 1,
in <module> TypeError: unhashable type: 'dict'

The type may be made cacheable by assigning a sorted tuple of tuples to the “.lookup” attribute:

class LookupType(UserDefinedType):
    """a custom type that accepts a dictionary as a parameter.

    The dictionary is stored both as itself in a private variable,
    and published in a public variable as a sorted tuple of tuples,
    which is hashable and will also return the same value for any
    two equivalent dictionaries.  Note it assumes the keys and
    values of the dictionary are themselves hashable.

    """

    cache_ok = True

    def __init__(self, lookup):
        self._lookup = lookup

        # assume keys/values of "lookup" are hashable; otherwise
        # they would also need to be converted in some way here
        self.lookup = tuple((key, lookup[key]) for key in sorted(lookup))

    def get_col_spec(self, **kw):
        return "VARCHAR(255)"

    def bind_processor(self, dialect): ...  # works with "self._lookup" ...

Where above, the cache key for LookupType({"a": 10, "b": 20}) will be:

>>> LookupType({"a": 10, "b": 20})._static_cache_key
(<class '__main__.LookupType'>, ('lookup', (('a', 10), ('b', 20))))

Added in version 1.4.14: - added the cache_ok flag to allow some configurability of caching for TypeDecorator classes.

Added in version 1.4.28: - added the ExternalType mixin which generalizes the cache_ok flag to both the TypeDecorator and UserDefinedType classes.

See also

sql_caching

impl: TypeEngine[Any] | Type[TypeEngine[Any]] = JSON()#

process_bind_param(value: Dict[str, Any] | None, _: Dialect) → Dict[str, Any]#

Receive a bound parameter value to be converted.

Custom subclasses of _types.TypeDecorator should override this method to provide custom behaviors for incoming data values. This method is called at statement execution time and is passed the literal Python data value which is to be associated with a bound parameter in the statement.

The operation could be anything desired to perform custom behavior, such as transforming or serializing data. This could also be used as a hook for validating logic.

Parameters:

value – Data to operate upon, of any type expected by this method in the subclass. Can be None.
dialect – the Dialect in use.

See also

types_typedecorator

_types.TypeDecorator.process_result_value()

class JsonList(*args: Any, **kwargs: Any)#

Bases: TypeDecorator

cache_ok: bool | None = True#

Indicate if statements using this ExternalType are “safe to cache”.

The default value None will emit a warning and then not allow caching of a statement which includes this type. Set to False to disable statements using this type from being cached at all without a warning. When set to True, the object’s class and selected elements from its state will be used as part of the cache key. For example, using a TypeDecorator:

class MyType(TypeDecorator):
    impl = String

    cache_ok = True

    def __init__(self, choices):
        self.choices = tuple(choices)
        self.internal_only = True

The cache key for the above type would be equivalent to:

>>> MyType(["a", "b", "c"])._static_cache_key
(<class '__main__.MyType'>, ('choices', ('a', 'b', 'c')))

The caching scheme will extract attributes from the type that correspond to the names of parameters in the __init__() method. Above, the “choices” attribute becomes part of the cache key but “internal_only” does not, because there is no parameter named “internal_only”.

The requirements for cacheable elements is that they are hashable and also that they indicate the same SQL rendered for expressions using this type every time for a given cache value.

To accommodate for datatypes that refer to unhashable structures such as dictionaries, sets and lists, these objects can be made “cacheable” by assigning hashable structures to the attributes whose names correspond with the names of the arguments. For example, a datatype which accepts a dictionary of lookup values may publish this as a sorted series of tuples. Given a previously un-cacheable type as:

class LookupType(UserDefinedType):
    """a custom type that accepts a dictionary as a parameter.

    this is the non-cacheable version, as "self.lookup" is not
    hashable.

    """

    def __init__(self, lookup):
        self.lookup = lookup

    def get_col_spec(self, **kw):
        return "VARCHAR(255)"

    def bind_processor(self, dialect): ...  # works with "self.lookup" ...

Where “lookup” is a dictionary. The type will not be able to generate a cache key:

>>> type_ = LookupType({"a": 10, "b": 20})
>>> type_._static_cache_key
<stdin>:1: SAWarning: UserDefinedType LookupType({'a': 10, 'b': 20}) will not
produce a cache key because the ``cache_ok`` flag is not set to True.
Set this flag to True if this type object's state is safe to use
in a cache key, or False to disable this warning.
symbol('no_cache')

If we did set up such a cache key, it wouldn’t be usable. We would get a tuple structure that contains a dictionary inside of it, which cannot itself be used as a key in a “cache dictionary” such as SQLAlchemy’s statement cache, since Python dictionaries aren’t hashable:

>>> # set cache_ok = True
>>> type_.cache_ok = True

>>> # this is the cache key it would generate
>>> key = type_._static_cache_key
>>> key
(<class '__main__.LookupType'>, ('lookup', {'a': 10, 'b': 20}))

>>> # however this key is not hashable, will fail when used with
>>> # SQLAlchemy statement cache
>>> some_cache = {key: "some sql value"}
Traceback (most recent call last): File "<stdin>", line 1,
in <module> TypeError: unhashable type: 'dict'

The type may be made cacheable by assigning a sorted tuple of tuples to the “.lookup” attribute:

class LookupType(UserDefinedType):
    """a custom type that accepts a dictionary as a parameter.

    The dictionary is stored both as itself in a private variable,
    and published in a public variable as a sorted tuple of tuples,
    which is hashable and will also return the same value for any
    two equivalent dictionaries.  Note it assumes the keys and
    values of the dictionary are themselves hashable.

    """

    cache_ok = True

    def __init__(self, lookup):
        self._lookup = lookup

        # assume keys/values of "lookup" are hashable; otherwise
        # they would also need to be converted in some way here
        self.lookup = tuple((key, lookup[key]) for key in sorted(lookup))

    def get_col_spec(self, **kw):
        return "VARCHAR(255)"

    def bind_processor(self, dialect): ...  # works with "self._lookup" ...

Where above, the cache key for LookupType({"a": 10, "b": 20}) will be:

>>> LookupType({"a": 10, "b": 20})._static_cache_key
(<class '__main__.LookupType'>, ('lookup', (('a', 10), ('b', 20))))

Added in version 1.4.14: - added the cache_ok flag to allow some configurability of caching for TypeDecorator classes.

Added in version 1.4.28: - added the ExternalType mixin which generalizes the cache_ok flag to both the TypeDecorator and UserDefinedType classes.

See also

sql_caching

impl: TypeEngine[Any] | Type[TypeEngine[Any]] = JSON()#

process_bind_param(value: List[Any] | None, _: Dialect) → List[Any]#

Receive a bound parameter value to be converted.

Custom subclasses of _types.TypeDecorator should override this method to provide custom behaviors for incoming data values. This method is called at statement execution time and is passed the literal Python data value which is to be associated with a bound parameter in the statement.

The operation could be anything desired to perform custom behavior, such as transforming or serializing data. This could also be used as a hook for validating logic.

Parameters:

value – Data to operate upon, of any type expected by this method in the subclass. Can be None.
dialect – the Dialect in use.

See also

types_typedecorator

_types.TypeDecorator.process_result_value()

class LatencyMs(*clauses: _ColumnExpressionOrLiteralArgument[Any])#

Bases: FunctionElement[float]

inherit_cache: bool | None = True#

Indicate if this HasCacheKey instance should make use of the cache key generation scheme used by its immediate superclass.

The attribute defaults to None, which indicates that a construct has not yet taken into account whether or not its appropriate for it to participate in caching; this is functionally equivalent to setting the value to False, except that a warning is also emitted.

This flag can be set to True on a particular class, if the SQL that corresponds to the object does not change based on attributes which are local to this class, and not its superclass.

See also

compilerext_caching - General guideslines for setting the HasCacheKey.inherit_cache attribute for third-party or user defined SQL constructs.

name = 'latency_ms'#

type: TypeEngine[_T] = Float()#

class Project(**kwargs)#

Bases: Base

created_at: Mapped[datetime]#

description: Mapped[str | None]#

gradient_end_color: Mapped[str]#

gradient_start_color: Mapped[str]#

id: Mapped[int]#

name: Mapped[str]#

traces: WriteOnlyMapped[List[Trace]]#

updated_at: Mapped[datetime]#

class Span(**kwargs)#

Bases: Base

attributes: Mapped[Dict[str, Any]]#

cumulative_error_count: Mapped[int]#

cumulative_llm_token_count_completion: Mapped[int]#

cumulative_llm_token_count_prompt: Mapped[int]#

cumulative_llm_token_count_total#

dataset_examples: Mapped[List[DatasetExample]]#

document_annotations: Mapped[List[DocumentAnnotation]]#

end_time: Mapped[datetime]#

events: Mapped[List[Dict[str, Any]]]#

id: Mapped[int]#

latency_ms#

name: Mapped[str]#

parent_id: Mapped[str | None]#

span_id: Mapped[str]#

span_kind: Mapped[str]#

start_time: Mapped[datetime]#

status_code: Mapped[str]#

status_message: Mapped[str]#

trace: Mapped[Trace]#

trace_rowid: Mapped[int]#

class SpanAnnotation(**kwargs)#

Bases: Base

annotator_kind: Mapped[str]#

created_at: Mapped[datetime]#

explanation: Mapped[str | None]#

id: Mapped[int]#

label: Mapped[str | None]#

metadata_: Mapped[Dict[str, Any]]#

name: Mapped[str]#

score: Mapped[float | None]#

span_rowid: Mapped[int]#

updated_at: Mapped[datetime]#

class TextContains(*clauses: _ColumnExpressionOrLiteralArgument[Any])#

Bases: FunctionElement[str]

inherit_cache: bool | None = True#

Indicate if this HasCacheKey instance should make use of the cache key generation scheme used by its immediate superclass.

The attribute defaults to None, which indicates that a construct has not yet taken into account whether or not its appropriate for it to participate in caching; this is functionally equivalent to setting the value to False, except that a warning is also emitted.

This flag can be set to True on a particular class, if the SQL that corresponds to the object does not change based on attributes which are local to this class, and not its superclass.

See also

compilerext_caching - General guideslines for setting the HasCacheKey.inherit_cache attribute for third-party or user defined SQL constructs.

name = 'text_contains'#

type: TypeEngine[_T] = String()#

class Trace(**kwargs)#

Bases: Base

end_time: Mapped[datetime]#

experiment_runs: Mapped[List[ExperimentRun]]#

id: Mapped[int]#

latency_ms#

project: Mapped[Project]#

project_rowid: Mapped[int]#

spans: Mapped[List[Span]]#

start_time: Mapped[datetime]#

trace_id: Mapped[str]#

class TraceAnnotation(**kwargs)#

Bases: Base

annotator_kind: Mapped[str]#

created_at: Mapped[datetime]#

explanation: Mapped[str | None]#

id: Mapped[int]#

label: Mapped[str | None]#

metadata_: Mapped[Dict[str, Any]]#

name: Mapped[str]#

score: Mapped[float | None]#

trace_rowid: Mapped[int]#

updated_at: Mapped[datetime]#

class UtcTimeStamp(*args: Any, **kwargs: Any)#

Bases: TypeDecorator

cache_ok: bool | None = True#

Indicate if statements using this ExternalType are “safe to cache”.

The default value None will emit a warning and then not allow caching of a statement which includes this type. Set to False to disable statements using this type from being cached at all without a warning. When set to True, the object’s class and selected elements from its state will be used as part of the cache key. For example, using a TypeDecorator:

class MyType(TypeDecorator):
    impl = String

    cache_ok = True

    def __init__(self, choices):
        self.choices = tuple(choices)
        self.internal_only = True

The cache key for the above type would be equivalent to:

>>> MyType(["a", "b", "c"])._static_cache_key
(<class '__main__.MyType'>, ('choices', ('a', 'b', 'c')))

The caching scheme will extract attributes from the type that correspond to the names of parameters in the __init__() method. Above, the “choices” attribute becomes part of the cache key but “internal_only” does not, because there is no parameter named “internal_only”.

The requirements for cacheable elements is that they are hashable and also that they indicate the same SQL rendered for expressions using this type every time for a given cache value.

To accommodate for datatypes that refer to unhashable structures such as dictionaries, sets and lists, these objects can be made “cacheable” by assigning hashable structures to the attributes whose names correspond with the names of the arguments. For example, a datatype which accepts a dictionary of lookup values may publish this as a sorted series of tuples. Given a previously un-cacheable type as:

class LookupType(UserDefinedType):
    """a custom type that accepts a dictionary as a parameter.

    this is the non-cacheable version, as "self.lookup" is not
    hashable.

    """

    def __init__(self, lookup):
        self.lookup = lookup

    def get_col_spec(self, **kw):
        return "VARCHAR(255)"

    def bind_processor(self, dialect): ...  # works with "self.lookup" ...

Where “lookup” is a dictionary. The type will not be able to generate a cache key:

>>> type_ = LookupType({"a": 10, "b": 20})
>>> type_._static_cache_key
<stdin>:1: SAWarning: UserDefinedType LookupType({'a': 10, 'b': 20}) will not
produce a cache key because the ``cache_ok`` flag is not set to True.
Set this flag to True if this type object's state is safe to use
in a cache key, or False to disable this warning.
symbol('no_cache')

If we did set up such a cache key, it wouldn’t be usable. We would get a tuple structure that contains a dictionary inside of it, which cannot itself be used as a key in a “cache dictionary” such as SQLAlchemy’s statement cache, since Python dictionaries aren’t hashable:

>>> # set cache_ok = True
>>> type_.cache_ok = True

>>> # this is the cache key it would generate
>>> key = type_._static_cache_key
>>> key
(<class '__main__.LookupType'>, ('lookup', {'a': 10, 'b': 20}))

>>> # however this key is not hashable, will fail when used with
>>> # SQLAlchemy statement cache
>>> some_cache = {key: "some sql value"}
Traceback (most recent call last): File "<stdin>", line 1,
in <module> TypeError: unhashable type: 'dict'

The type may be made cacheable by assigning a sorted tuple of tuples to the “.lookup” attribute:

class LookupType(UserDefinedType):
    """a custom type that accepts a dictionary as a parameter.

    The dictionary is stored both as itself in a private variable,
    and published in a public variable as a sorted tuple of tuples,
    which is hashable and will also return the same value for any
    two equivalent dictionaries.  Note it assumes the keys and
    values of the dictionary are themselves hashable.

    """

    cache_ok = True

    def __init__(self, lookup):
        self._lookup = lookup

        # assume keys/values of "lookup" are hashable; otherwise
        # they would also need to be converted in some way here
        self.lookup = tuple((key, lookup[key]) for key in sorted(lookup))

    def get_col_spec(self, **kw):
        return "VARCHAR(255)"

    def bind_processor(self, dialect): ...  # works with "self._lookup" ...

Where above, the cache key for LookupType({"a": 10, "b": 20}) will be:

>>> LookupType({"a": 10, "b": 20})._static_cache_key
(<class '__main__.LookupType'>, ('lookup', (('a', 10), ('b', 20))))

Added in version 1.4.14: - added the cache_ok flag to allow some configurability of caching for TypeDecorator classes.

Added in version 1.4.28: - added the ExternalType mixin which generalizes the cache_ok flag to both the TypeDecorator and UserDefinedType classes.

See also

sql_caching

impl: TypeEngine[Any] | Type[TypeEngine[Any]] = TIMESTAMP(timezone=True)#

process_bind_param(value: datetime | None, _: Dialect) → datetime | None#

Receive a bound parameter value to be converted.

Custom subclasses of _types.TypeDecorator should override this method to provide custom behaviors for incoming data values. This method is called at statement execution time and is passed the literal Python data value which is to be associated with a bound parameter in the statement.

The operation could be anything desired to perform custom behavior, such as transforming or serializing data. This could also be used as a hook for validating logic.

Parameters:

value – Data to operate upon, of any type expected by this method in the subclass. Can be None.
dialect – the Dialect in use.

See also

types_typedecorator

_types.TypeDecorator.process_result_value()

process_result_value(value: Any | None, _: Dialect) → datetime | None#

Receive a result-row column value to be converted.

Custom subclasses of _types.TypeDecorator should override this method to provide custom behaviors for data values being received in result rows coming from the database. This method is called at result fetching time and is passed the literal Python data value that’s extracted from a database result row.

The operation could be anything desired to perform custom behavior, such as transforming or deserializing data.

Parameters:

value – Data to operate upon, of any type expected by this method in the subclass. Can be None.
dialect – the Dialect in use.

See also

types_typedecorator

_types.TypeDecorator.process_bind_param()

async init_models(engine: AsyncEngine) → None#

db.models#

This Page