Update docs

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)
 

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.
 

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
 

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.
 

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.

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)

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)

src/infi/clickhouse_orm/system_models.py

@@ -1,6 +1,6 @@
 """
-This file contains system readonly models that can be got from database
+This file contains system readonly models that can be got from the database
-https://clickhouse.yandex/reference_en.html#System tables
+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):
         """