From 20e609f95224c84edc84e3c02fcaf5dc89a0cc37 Mon Sep 17 00:00:00 2001 From: Itai Shirav Date: Sat, 21 Apr 2018 15:23:00 +0300 Subject: [PATCH] Update docs --- docs/class_reference.md | 2 +- docs/field_types.md | 4 ++- docs/models_and_databases.md | 38 ++++++++++++++++++++++-- docs/system_models.md | 4 +-- docs/table_engines.md | 5 ++-- docs/toc.md | 4 +++ src/infi/clickhouse_orm/engines.py | 2 +- src/infi/clickhouse_orm/system_models.py | 8 ++--- 8 files changed, 54 insertions(+), 13 deletions(-) diff --git a/docs/class_reference.md b/docs/class_reference.md index b51c89f..edcf4f9 100644 --- a/docs/class_reference.md +++ b/docs/class_reference.md @@ -649,7 +649,7 @@ Extends Engine Buffers the data to write in RAM, periodically flushing it to another table. Must be used in conjuction with a `BufferModel`. -Read more [here](https://clickhouse.yandex/reference_en.html#Buffer). +Read more [here](https://clickhouse.yandex/docs/en/table_engines/buffer/). #### Buffer(main_model, num_layers=16, min_time=10, max_time=100, min_rows=10000, max_rows=1000000, min_bytes=10000000, max_bytes=100000000) diff --git a/docs/field_types.md b/docs/field_types.md index 80d0f2a..4c447eb 100644 --- a/docs/field_types.md +++ b/docs/field_types.md @@ -1,6 +1,8 @@ Field Types =========== +See: [ClickHouse Documentation](https://clickhouse.yandex/docs/en/data_types/) + Currently the following field types are supported: | Class | DB Type | Pythonic Type | Comments @@ -85,7 +87,7 @@ Working with materialized and alias fields ClickHouse provides an opportunity to create MATERIALIZED and ALIAS Fields. -See documentation [here](https://clickhouse.yandex/reference_en.html#Default%20values). +See documentation [here](https://clickhouse.yandex/docs/en/query_language/queries/#default-values). Both field types can't be inserted into the database directly, so they are ignored when using the `Database.insert()` method. ClickHouse does not return the field values if you use `"SELECT * FROM ..."` - you have to list these field names explicitly in the query. diff --git a/docs/models_and_databases.md b/docs/models_and_databases.md index 2b84f99..1919989 100644 --- a/docs/models_and_databases.md +++ b/docs/models_and_databases.md @@ -21,9 +21,43 @@ Models are defined in a way reminiscent of Django's ORM: engine = engines.MergeTree('birthday', ('first_name', 'last_name', 'birthday')) -It is possible to provide a default value for a field, instead of its "natural" default (empty string for string fields, zero for numeric fields etc.). Alternatively it is possible to pass alias or materialized parameters (see below for usage examples). Only one of `default`, `alias` and `materialized` parameters can be provided. +The database columns in the database table are represented by model fields. Each field has a type, which matches the type of the corresponding database column. You can see all the supported fields types [here](field_types.md). -For more details see [Field Types](field_types.md) and [Table Engines](table_engines.md). +A model must have an `engine`, which determines how its table is stored on disk (if at all), and what capabilities it has. For more details about table engines see [here](table_engines.md). + +### Default values + +Each field has a "natural" default value - empty string for string fields, zero for numeric fields etc. To specify a different value use the `default` parameter: + + first_name = fields.StringField(default="anonymous") + +### Null values + +To allow null values in a field, wrap it inside a `NullableField`: + + birthday = fields.NullableField(fields.DateField()) + +In this case, the default value for that fields becomes `null` unless otherwide specified. + +### Materialized fields + +The value of a materialized field is calculated from other fields in the model. For example: + + year_born = fields.Int16Field(materialized="toYear(birthday)") + +Materialized fields are read-only, meaning that their values are not sent to the database when inserting records. + +It is not possible to specify a default value for a materialized field. + +### Alias fields + +An alias field is is simply a different way to call another field in the model. For example: + + date_born = field.DateField(alias="birthday") + +Alias fields are read-only, meaning that their values are not sent to the database when inserting records. + +It is not possible to specify a default value for an alias field. ### Table Names diff --git a/docs/system_models.md b/docs/system_models.md index beed825..56ae447 100644 --- a/docs/system_models.md +++ b/docs/system_models.md @@ -1,7 +1,7 @@ System Models ============= -[Clickhouse docs](https://clickhouse.yandex/reference_en.html#System%20tables). +[Clickhouse docs](https://clickhouse.yandex/docs/en/system_tables/). System models are read only models for implementing part of the system's functionality, and for providing access to information about how the system is working. @@ -14,7 +14,7 @@ Currently the following system models are supported: Partitions and Parts -------------------- -[ClickHouse docs](https://clickhouse.yandex/reference_en.html#Manipulations%20with%20partitions%20and%20parts). +[ClickHouse docs](https://clickhouse.yandex/docs/en/query_language/queries/#manipulations-with-partitions-and-parts). A partition in a table is data for a single calendar month. Table "system.parts" contains information about each part. diff --git a/docs/table_engines.md b/docs/table_engines.md index 1ad3770..d4ba905 100644 --- a/docs/table_engines.md +++ b/docs/table_engines.md @@ -1,7 +1,7 @@ Table Engines ============= -See: [ClickHouse Documentation](https://clickhouse.yandex/reference_en.html#Table+engines) +See: [ClickHouse Documentation](https://clickhouse.yandex/docs/en/table_engines/) Each model must have an engine instance, used when creating the table in ClickHouse. @@ -110,7 +110,8 @@ Then you can insert objects into Buffer model and they will be handled by ClickH Merge Engine ------------- -[ClickHouse docs](https://clickhouse.yandex/docs/en/single/index.html#merge) +[ClickHouse docs](https://clickhouse.yandex/docs/en/table_engines/merge/) + A `Merge` engine is only used in conjunction with a `MergeModel`. This table does not store data itself, but allows reading from any number of other tables simultaneously. So you can't insert in it. Engine parameter specifies re2 (similar to PCRE) regular expression, from which data is selected. diff --git a/docs/toc.md b/docs/toc.md index c9c5ee9..2ed6e89 100644 --- a/docs/toc.md +++ b/docs/toc.md @@ -5,6 +5,10 @@ * [Models and Databases](models_and_databases.md#models-and-databases) * [Defining Models](models_and_databases.md#defining-models) + * [Default values](models_and_databases.md#default-values) + * [Null values](models_and_databases.md#null-values) + * [Materialized fields](models_and_databases.md#materialized-fields) + * [Alias fields](models_and_databases.md#alias-fields) * [Table Names](models_and_databases.md#table-names) * [Using Models](models_and_databases.md#using-models) * [Inserting to the Database](models_and_databases.md#inserting-to-the-database) diff --git a/src/infi/clickhouse_orm/engines.py b/src/infi/clickhouse_orm/engines.py index 97e0890..b1aa8f7 100644 --- a/src/infi/clickhouse_orm/engines.py +++ b/src/infi/clickhouse_orm/engines.py @@ -159,7 +159,7 @@ class Buffer(Engine): """ Buffers the data to write in RAM, periodically flushing it to another table. Must be used in conjuction with a `BufferModel`. - Read more [here](https://clickhouse.yandex/reference_en.html#Buffer). + Read more [here](https://clickhouse.yandex/docs/en/table_engines/buffer/). """ #Buffer(database, table, num_layers, min_time, max_time, min_rows, max_rows, min_bytes, max_bytes) diff --git a/src/infi/clickhouse_orm/system_models.py b/src/infi/clickhouse_orm/system_models.py index 8a5217a..7341d14 100644 --- a/src/infi/clickhouse_orm/system_models.py +++ b/src/infi/clickhouse_orm/system_models.py @@ -1,6 +1,6 @@ """ -This file contains system readonly models that can be got from database -https://clickhouse.yandex/reference_en.html#System tables +This file contains system readonly models that can be got from the database +https://clickhouse.yandex/docs/en/system_tables/ """ from __future__ import unicode_literals from six import string_types @@ -15,7 +15,7 @@ class SystemPart(Model): """ Contains information about parts of a table in the MergeTree family. This model operates only fields, described in the reference. Other fields are ignored. - https://clickhouse.yandex/reference_en.html#system.parts + https://clickhouse.yandex/docs/en/system_tables/system.parts/ """ OPERATIONS = frozenset({'DETACH', 'DROP', 'ATTACH', 'FREEZE', 'FETCH'}) @@ -56,7 +56,7 @@ class SystemPart(Model): """ Next methods return SQL for some operations, which can be done with partitions - https://clickhouse.yandex/reference_en.html#Manipulations with partitions and parts + https://clickhouse.yandex/docs/en/query_language/queries/#manipulations-with-partitions-and-parts """ def _partition_operation_sql(self, operation, settings=None, from_part=None): """