hare-orm 0.9.0__py3-none-any.whl

hare/dialects/clickhouse/schema/tables/clickhouse_table_partitions.py

@@ -0,0 +1,160 @@
+from __future__ import annotations
+
+import dataclasses
+from typing import TYPE_CHECKING, Any
+
+from hare.classes.comparable_values import ComparableValues
+from hare.dialects.base.schema.tables.table_partitions import TablePartitions
+from hare.dialects.clickhouse.clickhouse_table_options import ClickhouseTableOptions
+from hare.dialects.clickhouse.schema.constants import (
+    CLICKHOUSE_ALTERABLE_TABLE_OPTIONS,
+    CLICKHOUSE_CREATION_ONLY_TABLE_SETTINGS,
+    CLICKHOUSE_PROJECTION_REBUILD_SETTINGS,
+)
+
+if TYPE_CHECKING:
+    from hare.ddl.table_options import TableOptions
+    from hare.models import Model
+
+
+class ClickhouseTablePartitions(TablePartitions):
+    """A change of a ClickHouse table's options - by ``ALTER TABLE`` where the server changes the
+    option in place (the table's and its columns' time to live, its settings, the compression of its
+    columns, its projections), by remaking the table for its engine and its keys."""
+
+    __slots__ = ()
+
+    async def alter_table_options(
+        self, model: type[Model], old_options: TableOptions | None, new_options: TableOptions | None
+    ) -> None:
+        old = old_options if isinstance(old_options, ClickhouseTableOptions) else ClickhouseTableOptions()
+        new = new_options if isinstance(new_options, ClickhouseTableOptions) else ClickhouseTableOptions()
+        # The options a table is altered to are checked as those it is created with.
+        new.raise_if_unsupported(model, self.editor.client.features)
+        changed_options = {
+            option.name for option in dataclasses.fields(new) if getattr(old, option.name) != getattr(new, option.name)
+        }
+        old_settings, new_settings = dict(old.get_table_settings()), dict(new.get_table_settings())
+        changed_settings = {
+            name for name in {*old_settings, *new_settings} if old_settings.get(name) != new_settings.get(name)
+        }
+        if (
+            changed_options - CLICKHOUSE_ALTERABLE_TABLE_OPTIONS
+            or changed_settings & CLICKHOUSE_CREATION_ONLY_TABLE_SETTINGS
+        ):
+            await self.editor.table_rebuild.remake_table(model, model)
+            return
+        # Checked as a created table's options are - the remade table is.
+        new.raise_if_unsupported(model, self.editor.client.features)
+        for statement in self.get_alter_sqls(model, old, new):
+            await self.editor.run_sql(statement)
+
+    def get_alter_sqls(
+        self, model: type[Model], old: ClickhouseTableOptions, new: ClickhouseTableOptions
+    ) -> list[str]:
+        """The statements changing a table from its old options to its new ones in place.
+
+        Args:
+            model: The model rendered with its new options.
+            old: The table's options.
+            new: The options it gets.
+
+        Returns:
+            The statements.
+        """
+        quote = self.editor.quote
+        meta = model._meta
+        table_sql = self.editor.qualify_table_name(meta.db_table, meta.schema)
+        changes: list[str] = []
+        if not ComparableValues.are_equal(old.ttl, new.ttl):
+            changes.append(
+                "REMOVE TTL"
+                if new.ttl is None
+                else f"MODIFY TTL {new.get_expression_sql(model, new.ttl, self.editor)}"
+            )
+        old_settings, new_settings = dict(old.get_table_settings()), dict(new.get_table_settings())
+        modified_settings = [
+            f"{name} = {new.get_setting_sql(value)}"
+            for name, value in new_settings.items()
+            if old_settings.get(name) != value
+        ]
+        projection_settings_sql = new.get_projection_settings_sql()
+        if projection_settings_sql and not old.projections:
+            modified_settings.append(projection_settings_sql)
+        if modified_settings:
+            changes.append(f"MODIFY SETTING {', '.join(modified_settings)}")
+        reset_settings = [name for name in old_settings if name not in new_settings]
+        if reset_settings:
+            changes.append(f"RESET SETTING {', '.join(reset_settings)}")
+        changes.extend(
+            self.get_column_option_changes(model, dict(old.column_codecs), dict(new.column_codecs), "CODEC")
+        )
+        changes.extend(self.get_column_option_changes(model, dict(old.column_ttls), dict(new.column_ttls), "TTL"))
+        old_projections = {projection.name: projection for projection in old.projections}
+        new_projections = {projection.name: projection for projection in new.projections}
+        changes.extend(
+            f"DROP PROJECTION {quote(name)}"
+            for name, projection in old_projections.items()
+            if not ComparableValues.are_equal(new_projections.get(name), projection)
+        )
+        if old.get_projection_settings_sql() and not new.projections:
+            # The settings the projections were taken with go with the last of them - once it is dropped.
+            projection_settings = [
+                name
+                for name in CLICKHOUSE_PROJECTION_REBUILD_SETTINGS
+                if name not in old_settings and name not in new_settings
+            ]
+            if projection_settings:
+                changes.append(f"RESET SETTING {', '.join(projection_settings)}")
+        added_projections = [
+            projection
+            for name, projection in new_projections.items()
+            if not ComparableValues.are_equal(old_projections.get(name), projection)
+        ]
+        changes.extend(
+            f"ADD PROJECTION {projection.get_definition_sql(model, self.editor)}" for projection in added_projections
+        )
+        # A projection added to a table holding rows is built for them by a mutation of its own.
+        changes.extend(f"MATERIALIZE PROJECTION {quote(projection.name)}" for projection in added_projections)
+        return [f"ALTER TABLE {table_sql} {change}" for change in changes]
+
+    def get_column_option_changes(
+        self, model: type[Model], old_values: dict[str, Any], new_values: dict[str, Any], clause: str
+    ) -> list[str]:
+        """The changes of one option of the table's columns - set where it is new or another, removed
+        where it is gone.
+
+        Args:
+            model: The model.
+            old_values: The option of each field naming one.
+            new_values: The option each field gets.
+            clause: The option's clause - ``CODEC`` or ``TTL``.
+
+        Returns:
+            The ``MODIFY COLUMN`` changes.
+        """
+        quote = self.editor.quote
+        meta = model._meta
+        fields_db_projection = meta.fields_db_projection
+        column_definitions = self.editor.column_definitions
+        changes = []
+        for field_name, value in new_values.items():
+            if field_name in old_values and ComparableValues.are_equal(old_values[field_name], value):
+                continue
+            field = meta.fields_map[field_name]
+            # With its type: a clause right after the column's name is read as its type.
+            column_type = column_definitions.get_altered_column_type(
+                column_definitions.get_table_column_type(model, field), field.null
+            )
+            value_sql = (
+                f"CODEC({value})"
+                if clause == "CODEC"
+                else f"TTL {ClickhouseTableOptions.get_expression_sql(model, value, self.editor)}"
+            )
+            changes.append(f"MODIFY COLUMN {quote(fields_db_projection[field_name])} {column_type} {value_sql}")
+        changes.extend(
+            f"MODIFY COLUMN {quote(fields_db_projection[field_name])} REMOVE {clause}"
+            for field_name in old_values
+            if field_name not in new_values and field_name in fields_db_projection
+        )
+        return changes

hare/dialects/clickhouse/schema/tables/clickhouse_table_rebuild.py

@@ -0,0 +1,227 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Any
+
+from hare.dialects.base.schema.tables.table_rebuild import TableRebuild
+from hare.dialects.clickhouse.clickhouse_table_options import ClickhouseTableOptions
+from hare.dialects.clickhouse.client.constants import CLICKHOUSE_DEFAULT_DATABASE
+from hare.dialects.clickhouse.cluster.constants import (
+    CLICKHOUSE_CLUSTER_HOSTS_SQL,
+    CLICKHOUSE_DISTRIBUTED_TABLE_TEMPLATE,
+    CLICKHOUSE_REPLICATED_ENGINE_PREFIX,
+    CLICKHOUSE_SHARD_MACRO,
+)
+from hare.dialects.clickhouse.introspection.constants import CLICKHOUSE_TABLE_ENGINE_SQL
+from hare.exceptions import UnSupportedError
+from hare.fields.field import Field
+from hare.fields.relations.fields.foreign_key_field_instance import ForeignKeyFieldInstance
+from hare.models import Model
+
+if TYPE_CHECKING:
+    from hare.dialects.base.schema.data.referencing_key_columns import ReferencingKeyColumns
+    from hare.dialects.clickhouse.schema.declarations import ClickhouseSchemaEditor
+
+
+class ClickhouseTableRebuild(TableRebuild):
+    """TableRebuild as ClickHouse does it - the views and the dictionaries a model declares are dropped
+    before its table is remade and created again over the new one: a view follows the inserts of the
+    table it was created over, and would take the copied rows a second time; the server drops no table
+    a dictionary reads. The rows of a table distributed over a cluster are copied through it, each to
+    its shard."""
+
+    __slots__ = ()
+
+    editor: ClickhouseSchemaEditor
+
+    async def remake_table(
+        self,
+        old_model: type[Model],
+        new_model: type[Model],
+        altered_fields: Sequence[tuple[Field[Any], Field[Any]]] = (),
+    ) -> None:
+        """Rebuilds the table, the model's views and dictionaries created again over it - a
+        materialized view's own storage filled by its query, a table one writes to left with its rows.
+
+        Args:
+            old_model: The model the table matches now - its views and dictionaries are dropped.
+            new_model: The model the table is rebuilt to - its views and dictionaries are created.
+            altered_fields: (old, new) fields paired otherwise than by name - a renamed field.
+
+        Raises:
+            UnSupportedError: The table keeps rows of its own on several servers of the connection's
+                cluster - neither replicated nor distributed.
+        """
+        await self.raise_if_rows_are_scattered(new_model)
+        materialized_views = self.editor.materialized_views
+        await materialized_views.drop_model_materialized_views(old_model)
+        await self.editor.dictionaries.drop_model_dictionaries(old_model)
+        await self.editor.views.drop_model_views(old_model)
+        await super().remake_table(old_model, new_model, altered_fields)
+        meta = new_model._meta
+        for view in meta.views:
+            await self.editor.views.create_view(new_model, view)
+        for dictionary in meta.dictionaries:
+            await self.editor.dictionaries.create_dictionary(new_model, dictionary)
+        for materialized_view in meta.materialized_views:
+            await materialized_views.create_materialized_view_again(new_model, materialized_view)
+
+    async def remake_for_referencing_key_columns(self, referencing: ReferencingKeyColumns) -> bool:
+        """Remakes the table of a relation whose key columns are keys of the table - the server changes
+        no key column in place.
+
+        Args:
+            referencing: The relation key columns, with their new types.
+
+        Returns:
+            Whether the table was remade.
+        """
+        if not isinstance(referencing.relation_field, ForeignKeyFieldInstance) or not any(
+            self.is_key_column(referencing.model, column) for column, __ in referencing.key_columns
+        ):
+            return False
+        await self.remake_table(referencing.model, referencing.model)
+        return True
+
+    async def remake_for_column_change(self, model: type[Model], old_field: Field[Any], new_field: Field[Any]) -> bool:
+        """Remakes the table for a new type or nullability of a column of its keys - the server changes
+        no key column in place.
+
+        Args:
+            model: The model rendered from the state the table changes to.
+            old_field: The field before the change.
+            new_field: The field after it.
+
+        Returns:
+            Whether the table was remade.
+        """
+        dialect = self.editor.client.dialect
+        if (
+            old_field.get_column_type(dialect) == new_field.get_column_type(dialect)
+            and old_field.null == new_field.null
+        ):
+            return False
+        if not self.is_key_column(model, new_field.source_field or new_field.model_field_name):
+            return False
+        await self.remake_table(model, model, altered_fields=[(old_field, new_field)])
+        return True
+
+    def is_key_column(self, model: type[Model], column_name: str) -> bool:
+        """Whether a column is one of the table's keys.
+
+        Args:
+            model: The model of the table.
+            column_name: The column.
+
+        Returns:
+            True for a column of the primary key or read by a key expression.
+        """
+        meta = model._meta
+        if column_name in meta.get_column_names(meta.primary_key_attribute_names):
+            return True
+        dialect = self.editor.client.dialect
+        table_options = meta.get_table_options(dialect)
+        if not isinstance(table_options, ClickhouseTableOptions):
+            return False
+        return column_name in table_options.get_key_column_names(model, dialect)
+
+    def is_read_by_schema_objects(self, model: type[Model], field_name: str, column_name: str) -> bool:
+        """Whether a column is read by what the table's model declares over it - a projection, a
+        materialized view, a dictionary: the server renames no column one of them reads.
+
+        Args:
+            model: The model of the table.
+            field_name: The column's field.
+            column_name: The column.
+
+        Returns:
+            True for a column a projection's query or a dictionary reads, and for any column of a
+            table with a materialized view.
+        """
+        meta = model._meta
+        if meta.materialized_views:
+            return True
+        if any(field_name in dictionary.get_field_names() for dictionary in meta.dictionaries):
+            return True
+        table_options = meta.get_table_options(self.editor.client.dialect)
+        if not isinstance(table_options, ClickhouseTableOptions):
+            return False
+        # A raw SQL projection's columns are the ones it names in read_columns.
+        return any(column_name in projection.get_read_columns() for projection in table_options.projections)
+
+    async def raise_if_rows_are_scattered(self, model: type[Model]) -> None:
+        """Refuses to remake a table whose rows the connection's server holds only a part of.
+
+        Args:
+            model: The model.
+
+        Raises:
+            UnSupportedError: The table isn't distributed, and the connection's cluster has several servers
+                keeping rows of their own - several servers for a table of another engine, several shards
+                for a replicated one whose replica path names the shard: the rows of the others would be
+                lost, or copied into every shard.
+        """
+        client = self.editor.client
+        if client.cluster is None or self.editor.collect_sql:
+            return
+        options = ClickhouseTableOptions.get_for_model(model, client.dialect)
+        if options.distributed_over is not None:
+            return
+        rows = await client.execute_dicts(CLICKHOUSE_CLUSTER_HOSTS_SQL, [client.cluster.name])
+        if not rows:
+            return
+        if options.engine.startswith(CLICKHOUSE_REPLICATED_ENGINE_PREFIX):
+            if int(rows[0]["shards"]) > 1 and await self.is_replicated_per_shard(model):
+                raise UnSupportedError(
+                    f"{model.__name__}: the change remakes the table, whose replicas keep rows of their own on each "
+                    f"shard of the cluster {client.cluster.name!r} - the copy would read the rows of one shard. "
+                    "Distribute the table (ClickhouseTableOptions(distributed_over=...))"
+                )
+        elif int(rows[0]["hosts"]) > 1:
+            raise UnSupportedError(
+                f"{model.__name__}: the change remakes the table, which keeps rows of its own on each server of the "
+                f"cluster {client.cluster.name!r} - only the rows of this server would be copied. Store the table "
+                "by a Replicated engine, or distribute it (ClickhouseTableOptions(distributed_over=...))"
+            )
+
+    async def is_replicated_per_shard(self, model: type[Model]) -> bool:
+        """Whether the replicas of a replicated table are those of one shard - its replica path names the
+        shard (``{shard}``, as the server's default path does) - rather than every server of the cluster.
+
+        Args:
+            model: The model.
+
+        Returns:
+            Whether they are.
+        """
+        client = self.editor.client
+        meta = model._meta
+        rows = await client.execute_dicts(
+            CLICKHOUSE_TABLE_ENGINE_SQL, [meta.schema or client.database or CLICKHOUSE_DEFAULT_DATABASE, meta.db_table]
+        )
+        return not rows or CLICKHOUSE_SHARD_MACRO in str(rows[0]["engine_full"])
+
+    async def copy_table_rows(
+        self, model: type[Model], new_table_name: str, old_table_name: str, column_mapping: dict[str, str]
+    ) -> None:
+        """Copies the rows; those of a distributed table through a distributed table over the new
+        local ones - read from every shard, written each to its shard."""
+        client = self.editor.client
+        options = ClickhouseTableOptions.get_for_model(model, client.dialect)
+        if options.distributed_over is None or client.cluster is None:
+            await super().copy_table_rows(model, new_table_name, old_table_name, column_mapping)
+            return
+        meta = model._meta
+        distributed_copy_name = f"new__{meta.db_table}"
+        distributed_copy_sql = self.editor.qualify_table_name(distributed_copy_name, meta.schema)
+        await self.editor.run_sql(
+            CLICKHOUSE_DISTRIBUTED_TABLE_TEMPLATE.format(
+                or_replace="OR REPLACE ",
+                exists="",
+                table=distributed_copy_sql,
+                local_table=self.editor.qualify_table_name(new_table_name, meta.schema),
+                engine=options.get_distributed_engine_sql(model, self.editor, client.cluster.name, new_table_name),
+            )
+        )
+        await super().copy_table_rows(model, distributed_copy_name, meta.db_table, column_mapping)
+        await self.editor.run_sql(f"DROP TABLE {distributed_copy_sql}")

hare/dialects/clickhouse/schema_objects/__init__.py

@@ -0,0 +1,5 @@
+from hare.dialects.clickhouse.schema_objects.clickhouse_dictionary import ClickhouseDictionary
+from hare.dialects.clickhouse.schema_objects.clickhouse_materialized_view import ClickhouseMaterializedView
+from hare.dialects.clickhouse.schema_objects.clickhouse_projection import ClickhouseProjection
+
+__all__ = ["ClickhouseDictionary", "ClickhouseMaterializedView", "ClickhouseProjection"]

hare/dialects/clickhouse/schema_objects/clickhouse_dictionary.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from hare.classes.value_descriptions import ValueDescriptions
+from hare.ddl.raw_sql_term import RawSQLTerm
+from hare.ddl.schema_objects.dictionary import Dictionary
+from hare.dialects.clickhouse.schema.constants import (
+    CLICKHOUSE_DICTIONARY_DEFAULT_LAYOUT,
+    CLICKHOUSE_DICTIONARY_DIRECT_LAYOUT_NAMES,
+    CLICKHOUSE_DICTIONARY_LAYOUT_PATTERN,
+    CLICKHOUSE_DICTIONARY_LIFETIME_LIMIT,
+)
+from hare.exceptions import ConfigurationError
+
+
+@dataclass(frozen=True)
+class ClickhouseDictionary(Dictionary):
+    """A ClickHouse dictionary - rows of the model's table the server keeps in memory, a value of
+    them read by its key with ``DictGet`` in place of a JOIN::
+
+        class Country(Model):
+            code = fields.CharField(max_length=2, primary_key=True)
+            name = fields.CharField(max_length=50)
+
+            class Meta:
+                dictionaries = [ClickhouseDictionary("country_names", key=("code",), attributes=("name",))]
+
+    The dictionary is loaded from the model's table by the connection's own user, and again after
+    ``lifetime`` - a row written to the table is read through the dictionary after its next load
+    (``reload_dictionary()`` loads it at once).
+
+    Args:
+        name: The dictionary's name.
+        key: The fields of the model a row is looked up by.
+        attributes: The fields of the model a lookup gives.
+        layout: How the server keeps the rows, with its arguments - ``"COMPLEX_KEY_HASHED()"`` takes
+            a key of any fields; ``"HASHED()"``, ``"FLAT()"`` a key of one unsigned 64-bit integer.
+        lifetime: After how many seconds the dictionary is loaded again - a number, or the least
+            and the greatest of them (the server picks a moment in between); 0 for never.
+        source: ``RawSQLTerm`` of another source than the model's table, as ``SOURCE(...)`` takes it
+            - ``RawSQLTerm("POSTGRESQL(NAME orders_database TABLE 'country')")``. A ``{env:NAME}``
+            in it is replaced by the environment variable ``NAME`` when the dictionary is created -
+            a password stays out of the migration file.
+
+    Raises:
+        ConfigurationError: See ``Dictionary``; ``layout`` isn't a layout with its arguments,
+            ``lifetime`` isn't a number of seconds or a pair of them within ten years, ``source``
+            isn't ``RawSQLTerm`` of SQL.
+    """
+
+    layout: str = CLICKHOUSE_DICTIONARY_DEFAULT_LAYOUT
+    lifetime: int | tuple[int, int] = 0
+    source: RawSQLTerm | None = None
+
+    def __post_init__(self) -> None:
+        super().__post_init__()
+        owner = f"ClickhouseDictionary {self.name!r}"
+        if not isinstance(self.layout, str) or not CLICKHOUSE_DICTIONARY_LAYOUT_PATTERN.fullmatch(self.layout):
+            raise ConfigurationError(
+                f'{owner}: layout takes a layout with its arguments - "HASHED()", "CACHE(SIZE_IN_CELLS 1000)" - '
+                f"got {self.layout!r}"
+            )
+        seconds = self.lifetime if isinstance(self.lifetime, tuple) else (self.lifetime,)
+        if (
+            len(seconds) not in {1, 2}
+            or not all(
+                isinstance(value, int)
+                and not isinstance(value, bool)
+                and 0 <= value <= CLICKHOUSE_DICTIONARY_LIFETIME_LIMIT
+                for value in seconds
+            )
+            or seconds[0] > seconds[-1]
+        ):
+            raise ConfigurationError(
+                f"{owner}: lifetime takes a number of seconds from 0 to {CLICKHOUSE_DICTIONARY_LIFETIME_LIMIT}, or "
+                f"the least and the greatest of them, got {ValueDescriptions.get_shown_value(self.lifetime)}"
+            )
+        if self.keeps_no_rows() and self.lifetime != 0:
+            raise ConfigurationError(
+                f"{owner}: a {self.layout} dictionary keeps no rows - each lookup reads the source - so it takes no "
+                f"lifetime, got {self.lifetime!r}"
+            )
+        if self.source is not None and (not isinstance(self.source, RawSQLTerm) or not self.source.sql.strip()):
+            raise ConfigurationError(
+                f"{owner}: source takes RawSQLTerm(...) of a source as SOURCE(...) takes it, got "
+                f"{ValueDescriptions.get_shown_value(self.source)}"
+            )
+
+    def keeps_no_rows(self) -> bool:
+        """Whether the layout keeps no rows - a ``DIRECT`` one reads the source on each lookup and takes no
+        ``LIFETIME``.
+
+        Returns:
+            Whether it does.
+        """
+        return self.layout.partition("(")[0].strip().upper() in CLICKHOUSE_DICTIONARY_DIRECT_LAYOUT_NAMES
+
+    def get_lifetime_range(self) -> tuple[int, int]:
+        """The seconds the dictionary is loaded again after.
+
+        Returns:
+            The least and the greatest of them.
+        """
+        if isinstance(self.lifetime, tuple):
+            return self.lifetime
+        return 0, self.lifetime
+
+    def get_options(self) -> dict[str, Any]:
+        options: dict[str, Any] = {}
+        if self.layout != CLICKHOUSE_DICTIONARY_DEFAULT_LAYOUT:
+            options["layout"] = self.layout
+        if self.lifetime != 0:
+            options["lifetime"] = self.lifetime
+        if self.source is not None:
+            options["source"] = self.source
+        return options

hare/dialects/clickhouse/schema_objects/clickhouse_materialized_view.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Self, cast
+
+from hare.classes.value_descriptions import ValueDescriptions
+from hare.ddl.expressions.declared_expressions import DeclaredExpressions
+from hare.ddl.raw_sql_term import RawSQLTerm
+from hare.ddl.schema_objects.materialized_view import MaterializedView
+from hare.dialects.clickhouse.schema.constants import (
+    CLICKHOUSE_REFRESH_EVERY_KEYWORD,
+    CLICKHOUSE_REFRESH_SCHEDULE_PATTERN,
+)
+from hare.exceptions import ConfigurationError
+
+if TYPE_CHECKING:
+    from hare.query.expressions import Expression
+
+
+@dataclass(frozen=True)
+class ClickhouseMaterializedView(MaterializedView):
+    """A materialized view with what ClickHouse alone gives one - the table it writes its rows into,
+    the engine of the storage of its own, a refresh on a schedule::
+
+        class Visit(Model):
+            class Meta:
+                materialized_views = [
+                    ClickhouseMaterializedView(
+                        "visits_by_site",
+                        RawSQLTerm("SELECT site, count() AS visits FROM visit GROUP BY site"),
+                        engine="SummingMergeTree",
+                        order_by=("site",),
+                    )
+                ]
+
+    A ClickHouse materialized view follows the rows inserted into the table its query reads: each
+    inserted block goes through the query and into the view. A view with ``refresh`` holds the rows of
+    its whole query as of its last refresh instead. A plain ``MaterializedView`` is kept by a
+    ``MergeTree`` sorted by its ``unique_columns``.
+
+    Args:
+        name: The view's name.
+        query: The ``SELECT`` - as ``View.query``.
+        with_data: Fill the view with the rows its query gives when it is created.
+        unique_columns: What the rows are sorted by when ``order_by`` names nothing.
+        to: The table the view writes its rows into, in place of a storage of its own.
+        engine: The engine of the view's own storage, with its arguments.
+        order_by: What its own storage is sorted by - columns of the view, expressions of hare over the
+            fields of the model declaring the view that the view selects under their own names
+            (``Trunc("visited_at", "day")``), and ``RawSQLTerm`` expressions.
+        partition_by: The expression its own storage is partitioned by - a column, an expression of hare as
+            in ``order_by`` (``Trunc("visited_at", "month")``) or a ``RawSQLTerm``.
+        refresh: The schedule the view is refreshed on - ``"EVERY 1 HOUR"``, ``"AFTER 30 MINUTE"``,
+            with ``OFFSET ...`` and ``RANDOMIZE FOR ...`` as ClickHouse takes them.
+        append: A refresh adds its rows to the ones the view holds, instead of replacing them.
+        depends_on: The views refreshed on a schedule this one is refreshed after.
+
+    Raises:
+        ConfigurationError: See ``MaterializedView``; an argument of another type, ``to`` together
+            with a storage of the view's own, ``append`` or ``depends_on`` without ``refresh``.
+    """
+
+    to: str | None = None
+    engine: str = "MergeTree"
+    order_by: tuple[str | Expression | RawSQLTerm, ...] = ()
+    partition_by: str | Expression | RawSQLTerm | None = None
+    refresh: str | None = None
+    append: bool = False
+    depends_on: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        super().__post_init__()
+        owner = f"ClickhouseMaterializedView {self.name!r}"
+        if self.to is not None and (not isinstance(self.to, str) or not self.to.strip()):
+            raise ConfigurationError(f"{owner}: to must be a table name, got {self.to!r}")
+        if not isinstance(self.engine, str) or not self.engine.strip():
+            raise ConfigurationError(f"{owner}: engine must be a non-empty string, got {self.engine!r}")
+        if isinstance(cast("object", self.order_by), str) or not all(
+            DeclaredExpressions.is_declared_expression(key) for key in self.order_by
+        ):
+            raise ConfigurationError(
+                f"{owner}: order_by must be a sequence of column names, expressions of hare and RawSQLTerm(...) "
+                f"expressions, got {ValueDescriptions.get_shown_value(self.order_by)}"
+            )
+        if self.partition_by is not None and not DeclaredExpressions.is_declared_expression(self.partition_by):
+            raise ConfigurationError(
+                f"{owner}: partition_by takes a column, an expression of hare or RawSQLTerm(...) of a non-empty SQL "
+                f"expression, got {ValueDescriptions.get_shown_value(self.partition_by)}"
+            )
+        if self.refresh is not None and (
+            not isinstance(self.refresh, str)
+            or not CLICKHOUSE_REFRESH_SCHEDULE_PATTERN.fullmatch(self.refresh.strip())
+        ):
+            raise ConfigurationError(
+                f'{owner}: refresh takes a schedule - "EVERY 1 HOUR", "AFTER 30 MINUTE", with OFFSET and '
+                f"RANDOMIZE FOR - got {self.refresh!r}"
+            )
+        if isinstance(cast("object", self.depends_on), str) or not all(
+            isinstance(view_name, str) and view_name for view_name in self.depends_on
+        ):
+            raise ConfigurationError(f"{owner}: depends_on must be a sequence of view names, got {self.depends_on!r}")
+        object.__setattr__(self, "order_by", tuple(self.order_by))
+        object.__setattr__(self, "depends_on", tuple(self.depends_on))
+        if self.to is not None and (self.engine != "MergeTree" or self.order_by or self.partition_by is not None):
+            raise ConfigurationError(
+                f"{owner}: a view writing to {self.to!r} has no storage of its own - engine, order_by and "
+                "partition_by are those of that table"
+            )
+        if self.refresh is None and (self.append or self.depends_on):
+            raise ConfigurationError(f"{owner}: append and depends_on are of a view with a refresh schedule")
+        if (
+            self.depends_on
+            and self.refresh is not None
+            and not self.refresh.strip().upper().startswith(CLICKHOUSE_REFRESH_EVERY_KEYWORD)
+        ):
+            raise ConfigurationError(
+                f"{owner}: depends_on is of a view refreshed EVERY a period - ClickHouse refreshes a view AFTER "
+                f"one on its own, got {self.refresh!r}"
+            )
+
+    @classmethod
+    def from_materialized_view(cls, view: MaterializedView) -> Self:
+        """A materialized view as ClickHouse keeps it.
+
+        Args:
+            view: The view.
+
+        Returns:
+            The view itself when it is one of ClickHouse's, else one of a storage of its own.
+        """
+        if isinstance(view, cls):
+            return view
+        return cls(name=view.name, query=view.query, with_data=view.with_data, unique_columns=view.unique_columns)
+
+    def get_sort_keys(self) -> tuple[str | Expression | RawSQLTerm, ...]:
+        """What the view's own storage is sorted by.
+
+        Returns:
+            ``order_by``, or ``unique_columns`` where it names nothing.
+        """
+        return self.order_by or self.unique_columns
+
+    def get_options(self) -> dict[str, Any]:
+        options = super().get_options()
+        if self.to is not None:
+            options["to"] = self.to
+        if self.engine != "MergeTree":
+            options["engine"] = self.engine
+        if self.order_by:
+            options["order_by"] = self.order_by
+        if self.partition_by is not None:
+            options["partition_by"] = self.partition_by
+        if self.refresh is not None:
+            options["refresh"] = self.refresh
+        if self.append:
+            options["append"] = True
+        if self.depends_on:
+            options["depends_on"] = self.depends_on
+        return options