sqlalchemy_singlestoredb.ShardKey¶

class sqlalchemy_singlestoredb.ShardKey(*columns: str | Tuple[str, str], index_type: str | None = None, metadata_only: bool = False)¶

SingleStore SHARD KEY DDL element.

Represents a SHARD KEY constraint for distributing table data across partitions (leaf nodes) in a SingleStore cluster. Proper shard key selection is critical for query performance and data distribution.

Parameters:

*columns (Union[str, Tuple[str, str]]) – Variable number of column specifications for the shard key. Each column can be either: - A string column name (defaults to ASC) - A tuple of (column_name, direction) where direction is ‘ASC’ or ‘DESC’ For empty shard key (keyless sharding), pass no arguments.
index_type (str, optional, keyword-only) – Index type for the shard key. Options: ‘BTREE’ or ‘HASH’.
metadata_only (bool, default False, keyword-only) – If True, generates SHARD KEY … METADATA_ONLY syntax which prevents index creation on the shard key columns to save memory.

Examples

Basic shard key:

>>> ShardKey('user_id')

Multi-column shard key:

>>> ShardKey('user_id', 'category_id')

Empty shard key for keyless sharding:

>>> ShardKey()

With explicit ASC/DESC directions:

>>> ShardKey('user_id', ('category_id', 'DESC'))

Using static helper methods:

>>> ShardKey(ShardKey.asc('user_id'), ShardKey.desc('category_id'))

With index type:

>>> ShardKey('user_id', index_type='HASH')

With METADATA_ONLY to prevent index creation:

>>> ShardKey('user_id', metadata_only=True)

Table Usage:

from sqlalchemy import Column, Integer, MetaData, String, Table
from sqlalchemy_singlestoredb import ShardKey
metadata = MetaData()
users = Table(
    'users', metadata,
    Column('user_id', Integer, primary_key=True),
    Column('name', String(100)),
    singlestoredb_shard_key=ShardKey('user_id'),
)
# Multi-column shard key
orders = Table(
    'orders', metadata,
    Column('user_id', Integer),
    Column('order_id', Integer),
    Column('amount', Integer),
    singlestoredb_shard_key=ShardKey('user_id', 'order_id'),
)

ORM Usage:

from sqlalchemy import Column, Integer, String
from sqlalchemy.orm import declarative_base
from sqlalchemy_singlestoredb import ShardKey
Base = declarative_base()
class User(Base):
    __tablename__ = 'users'
    user_id = Column(Integer, primary_key=True)
    name = Column(String(100))
    __table_args__ = {
        'singlestoredb_shard_key': ShardKey('user_id'),
    }
class Order(Base):
    __tablename__ = 'orders'
    user_id = Column(Integer, primary_key=True)
    order_id = Column(Integer, primary_key=True)
    amount = Column(Integer)
    __table_args__ = {
        'singlestoredb_shard_key': ShardKey('user_id', 'order_id'),
    }

__init__(*columns: str | Tuple[str, str], index_type: str | None = None, metadata_only: bool = False) → None¶

Methods

`__init__`(*columns[, index_type, metadata_only])
`against`(target)	Return a copy of this `_schema.ExecutableDDLElement` which will include the given target.
`asc`(column)	Create an ascending shard key column specification.
`compare`(other, **kw)	Compare this `_expression.ClauseElement` to the given `_expression.ClauseElement`.
`compile`([bind, dialect])	Compile this SQL expression.
`desc`(column)	Create a descending shard key column specification.
`execute_if`([dialect, callable_, state])	Return a callable that will execute this `_ddl.ExecutableDDLElement` conditionally within an event handler.
`execution_options`(**kw)	Set non-SQL options for the statement which take effect during execution.
`get_children`(*[, omit_attrs])	Return immediate child `visitors.HasTraverseInternals` elements of this `visitors.HasTraverseInternals`.
`get_execution_options`()	Get the non-SQL options which will take effect during execution.
`memoized_instancemethod`(fn)	Decorate a method memoize its return value.
`options`(*options)	Apply options to this statement.
`params`([_ClauseElement__optionaldict])	Return a copy with `_expression.bindparam()` elements replaced.
`self_group`([against])	Apply a 'grouping' to this `_expression.ClauseElement`.
`unique_params`([_ClauseElement__optionaldict])	Return a copy with `_expression.bindparam()` elements replaced.

Attributes

`allows_lambda`
`description`
`entity_namespace`
`inherit_cache`	Indicate if this `HasCacheKey` instance should make use of the cache key generation scheme used by its immediate superclass.
`is_clause_element`
`is_delete`
`is_dml`
`is_from_statement`
`is_insert`
`is_select`
`is_selectable`
`is_text`
`is_update`
`stringify_dialect`
`supports_execution`
`target`
`uses_inspection`
`columns`
`index_type`
`metadata_only`
`negation_clause`
`proxy_set`