PERMANENTLY`. Если его не использовать, таблицы будут снова подключены при перезапуске кластера, например во время обновления.
+В ClickHouse Cloud пользователям следует использовать ключевое слово `PERMANENTLY`, например: `DETACH TABLE <table> PERMANENTLY`. Если его не использовать, таблицы будут снова подключены при перезапуске кластера, например во время обновления.
:::
**См. также**
* [Материализованное представление](/sql-reference/statements/create/view#materialized-view)
-* [Словари](../../sql-reference/dictionaries/index.md)
+* [Словари](./create/dictionary/index.md)
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/statements/exchange.md b/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/statements/exchange.md
index 8cb5a5103bd..3e1dbaab916 100644
--- a/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/statements/exchange.md
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/statements/exchange.md
@@ -104,4 +104,4 @@ EXCHANGE DICTIONARIES [db0.]dict_A AND [db1.]dict_B [ON CLUSTER cluster]
**См. также**
-* [Справочники](../../sql-reference/dictionaries/index.md)
+* [Справочники](./create/dictionary/index.md)
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/statements/optimize.md b/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/statements/optimize.md
index 5c89d2c11b0..d5405161da8 100644
--- a/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/statements/optimize.md
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/statements/optimize.md
@@ -19,6 +19,10 @@ doc_type: 'reference'
OPTIMIZE TABLE [db.]name [ON CLUSTER cluster] [PARTITION partition | PARTITION ID 'partition_id'] [FINAL | FORCE] [DEDUPLICATE [BY expression]]
```
+```sql
+OPTIMIZE TABLE [db.]name DRY RUN PARTS 'part_name1', 'part_name2' [, ...] [DEDUPLICATE [BY expression]] [CLEANUP]
+```
+
Запрос `OPTIMIZE` поддерживается для семейства [MergeTree](../../engines/table-engines/mergetree-family/mergetree.md) (включая [materialized views](/sql-reference/statements/create/view#materialized-view)) и движка [Buffer](../../engines/table-engines/special/buffer.md). Другие табличные движки `OPTIMIZE` не поддерживают.
Когда `OPTIMIZE` используется с семейством табличных движков [ReplicatedMergeTree](../../engines/table-engines/mergetree-family/replication.md), ClickHouse создает задачу на выполнение слияния и ожидает её завершения на всех репликах (если настройка [alter_sync](/operations/settings/settings#alter_sync) установлена в значение `2`) или на текущей реплике (если настройка [alter_sync](/operations/settings/settings#alter_sync) установлена в значение `1`).
@@ -34,6 +38,55 @@ OPTIMIZE TABLE [db.]name [ON CLUSTER cluster] [PARTITION partition | PARTITION I
Если `alter_sync` установлен в значение `2`, и некоторые реплики неактивны дольше времени, заданного настройкой `replication_wait_for_inactive_replica_timeout`, генерируется исключение `UNFINISHED`.
:::
+## DRY RUN \{#dry-run\}
+
+Предложение `DRY RUN` имитирует слияние указанных частей без фиксации результата. Слитая часть записывается во временное место на диске, проходит проверку и затем удаляется. Исходные части и данные таблицы остаются неизменными.
+
+Это полезно для:
+
+* Тестирования корректности слияния между разными версиями ClickHouse.
+* Детерминированного воспроизведения ошибок, связанных со слияниями.
+* Измерения производительности слияния.
+
+`DRY RUN` поддерживается только для таблиц семейства [MergeTree](../../engines/table-engines/mergetree-family/mergetree.md). Требуется ключевое слово `PARTS` со списком имён частей. Все указанные части должны существовать, быть активными и принадлежать одной и той же партиции.
+
+`DRY RUN` несовместим с `FINAL` и `PARTITION`. Его можно комбинировать с `DEDUPLICATE` (с необязательным указанием столбцов) и `CLEANUP` (для таблиц `ReplacingMergeTree`).
+
+**Синтаксис**
+
+```sql
+OPTIMIZE TABLE [db.]name DRY RUN PARTS 'part_name1', 'part_name2' [, ...] [DEDUPLICATE [BY expression]] [CLEANUP]
+```
+
+По умолчанию результирующая часть после слияния проверяется аналогично запросу [`CHECK TABLE`](/sql-reference/statements/check-table). Это поведение контролируется настройкой [optimize_dry_run_check_part](/operations/settings/settings#optimize_dry_run_check_part) (включена по умолчанию). При её отключении валидация не выполняется, что может быть полезно для бенчмаркинга самой операции слияния.
+
+**Пример**
+
+```sql
+CREATE TABLE dry_run_example (key UInt64, value String) ENGINE = MergeTree ORDER BY key;
+
+INSERT INTO dry_run_example VALUES (1, 'a'), (2, 'b');
+INSERT INTO dry_run_example VALUES (1, 'c'), (4, 'd');
+
+-- Simulate merging using two parts
+OPTIMIZE TABLE dry_run_example DRY RUN PARTS 'all_1_1_0', 'all_2_2_0';
+
+-- Simulate merging with deduplication
+OPTIMIZE TABLE dry_run_example DRY RUN PARTS 'all_1_1_0', 'all_2_2_0' DEDUPLICATE;
+
+-- Parts and data remain unchanged after DRY RUN
+SELECT name, rows FROM system.parts
+WHERE database = currentDatabase() AND table = 'dry_run_example' AND active
+ORDER BY name;
+```
+
+```response
+┌─name────────┬─rows─┐
+│ all_1_1_0 │ 2 │
+│ all_2_2_0 │ 2 │
+└─────────────┴──────┘
+```
+
## Выражение BY \{#by-expression\}
Если вы хотите выполнять дедупликацию по произвольному набору столбцов, а не по всем, вы можете явно указать список столбцов или использовать любую комбинацию выражений [`*`](../../sql-reference/statements/select/index.md#asterisk), [`COLUMNS`](/sql-reference/statements/select#select-clause) или [`EXCEPT`](/sql-reference/statements/select/except-modifier). Явно заданный или неявно развёрнутый список столбцов должен включать все столбцы, указанные в выражении упорядочивания строк (как первичного, так и сортировочного ключей), а также в выражении партиционирования (ключ партиционирования).
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/statements/rename.md b/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/statements/rename.md
index cd00fab3ad0..c3a946fcc81 100644
--- a/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/statements/rename.md
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/statements/rename.md
@@ -65,4 +65,4 @@ RENAME DICTIONARY [db0.]dict_A TO [db1.]dict_B [,...] [ON CLUSTER cluster]
**См. также**
-* [Справочники](../../sql-reference/dictionaries/index.md)
+* [Справочники](./create/dictionary/index.md)
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/statements/select/join.md b/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/statements/select/join.md
index 006306b7463..b56575425e4 100644
--- a/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/statements/select/join.md
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/statements/select/join.md
@@ -488,7 +488,7 @@ SELECT a, b, toTypeName(a), toTypeName(b) FROM t_1 FULL JOIN t_2 USING (a, b);
В некоторых случаях эффективнее использовать [IN](../../../sql-reference/operators/in.md) вместо `JOIN`.
-Если вам нужен `JOIN` для соединения с таблицами измерений (это относительно небольшие таблицы, содержащие свойства измерений, такие как имена рекламных кампаний), `JOIN` может быть не очень удобен из-за того, что правая таблица повторно читается для каждого запроса. Для таких случаев существует функциональность «словарей» (dictionaries), которую следует использовать вместо `JOIN`. Подробности см. в разделе [Dictionaries](../../../sql-reference/dictionaries/index.md).
+Если вам нужен `JOIN` для соединения с таблицами измерений (это относительно небольшие таблицы, содержащие свойства измерений, такие как имена рекламных кампаний), `JOIN` может быть не очень удобен из-за того, что правая таблица повторно читается для каждого запроса. Для таких случаев существует функциональность «словарей» (dictionaries), которую следует использовать вместо `JOIN`. Подробности см. в разделе [Dictionaries](../../create/dictionary/index.md).
### Ограничения по памяти \{#memory-limitations\}
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/statements/show.md b/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/statements/show.md
index ff078695233..a45c6506810 100644
--- a/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/statements/show.md
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/statements/show.md
@@ -247,7 +247,7 @@ SHOW COLUMNS FROM 'orders' LIKE 'delivery_%'
## SHOW DICTIONARIES \{#show-dictionaries\}
-Оператор `SHOW DICTIONARIES` отображает список [словарей](../../sql-reference/dictionaries/index.md).
+Оператор `SHOW DICTIONARIES` отображает список [словарей](./create/dictionary/index.md).
### Синтаксис \{#syntax-4\}
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/statements/system.md b/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/statements/system.md
index aa9fe2df862..7ccc2bb6059 100644
--- a/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/statements/system.md
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/statements/system.md
@@ -13,7 +13,7 @@ import CloudNotSupportedBadge from '@theme/badges/CloudNotSupportedBadge';
## SYSTEM RELOAD EMBEDDED DICTIONARIES \{#reload-embedded-dictionaries\}
-Перезагружает все [внутренние словари](../../sql-reference/dictionaries/index.md).
+Перезагружает все [внутренние словари](./create/dictionary/index.md).
По умолчанию внутренние словари отключены.
Всегда возвращает `Ok.` независимо от результата обновления внутреннего словаря.
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/table-functions/dictionary.md b/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/table-functions/dictionary.md
index 31af501e756..3d3858825f2 100644
--- a/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/table-functions/dictionary.md
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/table-functions/dictionary.md
@@ -10,7 +10,7 @@ doc_type: 'reference'
# Табличная функция dictionary \{#dictionary-table-function\}
-Отображает данные словаря [dictionary](../../sql-reference/dictionaries/index.md) в виде таблицы ClickHouse. Работает так же, как движок [Dictionary](../../engines/table-engines/special/dictionary.md).
+Отображает данные словаря [dictionary](../statements/create/dictionary/index.md) в виде таблицы ClickHouse. Работает так же, как движок [Dictionary](../../engines/table-engines/special/dictionary.md).
## Синтаксис \{#syntax\}
@@ -18,6 +18,7 @@ doc_type: 'reference'
dictionary('dict')
```
+
## Аргументы \{#arguments\}
- `dict` — Имя словаря. [String](../../sql-reference/data-types/string.md).
@@ -59,6 +60,7 @@ SELECT * FROM dictionary('new_dictionary');
└────┴───────┘
```
+
## См. также \{#related\}
-- [Движок Dictionary](/engines/table-engines/special/dictionary)
+- [Движок Dictionary](/engines/table-engines/special/dictionary)
\ No newline at end of file
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/table-functions/iceberg.md b/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/table-functions/iceberg.md
index f324565650e..d913de5b00e 100644
--- a/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/table-functions/iceberg.md
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/table-functions/iceberg.md
@@ -431,7 +431,7 @@ y: 993
### Эволюция схемы \{#iceberg-writes-schema-evolution\}
-ClickHouse позволяет добавлять, удалять или изменять столбцы с простыми типами данных (не `tuple`, не `array`, не `map`).
+ClickHouse позволяет добавлять, удалять, изменять или переименовывать столбцы с простыми типами данных (не `tuple`, не `array`, не `map`).
### Пример \{#example-iceberg-writes-evolution\}
@@ -490,8 +490,30 @@ Row 1:
──────
x: Ivanov
y: 993
+
+ALTER TABLE iceberg_writes_example RENAME COLUMN y TO value;
+SHOW CREATE TABLE iceberg_writes_example;
+
+ ┌─statement─────────────────────────────────────────────────┐
+1. │ CREATE TABLE default.iceberg_writes_example ↴│
+ │↳( ↴│
+ │↳ `x` Nullable(String), ↴│
+ │↳ `value` Nullable(Int64) ↴│
+ │↳) ↴│
+ │↳ENGINE = IcebergLocal('/home/scanhex12/iceberg_example/') │
+ └───────────────────────────────────────────────────────────┘
+
+SELECT *
+FROM iceberg_writes_example
+FORMAT VERTICAL;
+
+Row 1:
+──────
+x: Ivanov
+value: 993
```
+
### Компакция \{#iceberg-writes-compaction\}
ClickHouse поддерживает компакцию таблиц Iceberg. В настоящее время он может объединять файлы позиционных удалений (position delete files) с файлами данных с одновременным обновлением метаданных. Идентификаторы и метки времени предыдущих снимков (snapshot IDs and timestamps) остаются неизменными, поэтому функция time-travel по‑прежнему может использоваться с теми же значениями.
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/table-functions/mongodb.md b/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/table-functions/mongodb.md
index 3c5be2806fd..3cf93bf2f34 100644
--- a/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/table-functions/mongodb.md
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/table-functions/mongodb.md
@@ -129,4 +129,4 @@ SELECT * FROM mongodb(
## См. также \{#related\}
- [Движок таблицы `MongoDB`](engines/table-engines/integrations/mongodb.md)
-- [Использование MongoDB в качестве источника словаря](sql-reference/dictionaries/index.md#mongodb)
\ No newline at end of file
+- [Использование MongoDB в качестве источника словаря](../statements/create/dictionary/sources.md#mongodb)
\ No newline at end of file
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/table-functions/mysql.md b/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/table-functions/mysql.md
index 45c453dc481..8765a8e02e3 100644
--- a/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/table-functions/mysql.md
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/table-functions/mysql.md
@@ -18,6 +18,7 @@ doc_type: 'reference'
mysql({host:port, database, table, user, password[, replace_query, on_duplicate_clause] | named_collection[, option=value [,..]]})
```
+
## Аргументы \{#arguments\}
| Аргумент | Описание |
@@ -48,6 +49,7 @@ SELECT name FROM mysql(`mysql{1|2|3}:3306`, 'mysql_database', 'mysql_table', 'us
SELECT name FROM mysql(`mysql1:3306|mysql2:3306|mysql3:3306`, 'mysql_database', 'mysql_table', 'user', 'password');
```
+
## Возвращаемое значение \{#returned_value\}
Объект таблицы с теми же столбцами, что и исходная таблица MySQL.
@@ -143,11 +145,12 @@ SELECT * FROM mysql('host:port', 'database', 'table', 'user', 'password')
WHERE id > (SELECT max(id) FROM mysql_copy);
```
+
## См. также \{#related\}
- [Движок таблицы MySQL](../../engines/table-engines/integrations/mysql.md)
-- [Использование MySQL в качестве источника словаря](/sql-reference/dictionaries#mysql)
+- [Использование MySQL в качестве источника словаря](/sql-reference/statements/create/dictionary/sources#mysql)
- [mysql_datatypes_support_level](operations/settings/settings.md#mysql_datatypes_support_level)
- [mysql_map_fixed_string_to_text_in_show_columns](operations/settings/settings.md#mysql_map_fixed_string_to_text_in_show_columns)
- [mysql_map_string_to_text_in_show_columns](operations/settings/settings.md#mysql_map_string_to_text_in_show_columns)
-- [mysql_max_rows_to_insert](operations/settings/settings.md#mysql_max_rows_to_insert)
+- [mysql_max_rows_to_insert](operations/settings/settings.md#mysql_max_rows_to_insert)
\ No newline at end of file
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/table-functions/odbc.md b/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/table-functions/odbc.md
index 2a16229270e..8839b79b2ca 100644
--- a/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/table-functions/odbc.md
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/table-functions/odbc.md
@@ -19,6 +19,7 @@ odbc(datasource, external_table)
odbc(named_collection)
```
+
## Аргументы \{#arguments\}
| Аргумент | Описание |
@@ -110,7 +111,8 @@ SELECT * FROM odbc('DSN=mysqlconn', 'test', 'test')
└────────┴──────────────┴───────┴────────────────┘
```
+
## См. также \{#see-also\}
-- [Словари ODBC](/sql-reference/dictionaries#dbms)
-- [Табличный движок ODBC](/engines/table-engines/integrations/odbc).
+- [Словари ODBC](/sql-reference/statements/create/dictionary/sources#dbms)
+- [Табличный движок ODBC](/engines/table-engines/integrations/odbc).
\ No newline at end of file
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/table-functions/postgresql.md b/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/table-functions/postgresql.md
index c3a6cf1d913..b07a09be5ed 100644
--- a/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/table-functions/postgresql.md
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/table-functions/postgresql.md
@@ -17,6 +17,7 @@ doc_type: 'reference'
postgresql({host:port, database, table, user, password[, schema, [, on_conflict]] | named_collection[, option=value [,..]]})
```
+
## Аргументы \{#arguments\}
| Аргумент | Описание |
@@ -67,7 +68,8 @@ SELECT name FROM postgresql(`postgres{1|2|3}:5432`, 'postgres_database', 'postgr
SELECT name FROM postgresql(`postgres1:5431|postgres2:5432`, 'postgres_database', 'postgres_table', 'user', 'password');
```
-Поддерживаются приоритеты реплик для источника словаря PostgreSQL. Чем больше число в отображении, тем ниже приоритет. Наивысший приоритет — `0`.
+Поддерживаются приоритеты реплик для источника словаря PostgreSQL. Чем больше значение в отображении (map), тем ниже приоритет. Наивысший приоритет — `0`.
+
## Примеры \{#examples\}
@@ -94,7 +96,7 @@ postgresql> SELECT * FROM test;
(1 row)
```
-Выбор данных из ClickHouse с использованием простых аргументов:
+Выбор данных из ClickHouse с использованием позиционных аргументов:
```sql
SELECT * FROM postgresql('localhost:5432', 'test', 'test', 'postgresql_user', 'password') WHERE str IN ('test');
@@ -132,7 +134,7 @@ SELECT * FROM postgresql('localhost:5432', 'test', 'test', 'postgresql_user', 'p
└────────┴──────────────┴───────┴──────┴────────────────┘
```
-Использование нестандартной схемы:
+Использование схемы, отличной от схемы по умолчанию:
```text
postgres=# CREATE SCHEMA "nice.schema";
@@ -147,11 +149,12 @@ CREATE TABLE pg_table_schema_with_dots (a UInt32)
ENGINE PostgreSQL('localhost:5432', 'clickhouse', 'nice.table', 'postgrsql_user', 'password', 'nice.schema');
```
+
## Связанные материалы \{#related\}
- [Движок таблиц PostgreSQL](../../engines/table-engines/integrations/postgresql.md)
-- [Использование PostgreSQL как источника словаря](/sql-reference/dictionaries#postgresql)
+- [Использование PostgreSQL как источника словаря](/sql-reference/statements/create/dictionary/sources#postgresql)
### Репликация или миграция данных Postgres с помощью PeerDB \{#replicating-or-migrating-postgres-data-with-with-peerdb\}
-> В дополнение к табличным функциям вы всегда можете использовать [PeerDB](https://docs.peerdb.io/introduction) от ClickHouse для настройки непрерывного конвейера передачи данных из Postgres в ClickHouse. PeerDB — это специализированный инструмент, разработанный для репликации данных из Postgres в ClickHouse с использованием фиксации изменений данных (CDC).
+> В дополнение к табличным функциям вы всегда можете использовать [PeerDB](https://docs.peerdb.io/introduction) от ClickHouse для настройки непрерывного конвейера передачи данных из Postgres в ClickHouse. PeerDB — это специализированный инструмент, разработанный для репликации данных из Postgres в ClickHouse с использованием фиксации изменений данных (CDC).
\ No newline at end of file
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/table-functions/redis.md b/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/table-functions/redis.md
index 0144d8468f1..12bbe7aca66 100644
--- a/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/table-functions/redis.md
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/table-functions/redis.md
@@ -17,6 +17,7 @@ doc_type: 'reference'
redis(host:port, key, structure[, db_index[, password[, pool_size]]])
```
+
## Аргументы \{#arguments\}
| Argument | Description |
@@ -59,7 +60,8 @@ INSERT INTO TABLE FUNCTION redis(
'key String, v1 String, v2 UInt32') values ('1', '1', 1);
```
+
## См. также \{#related\}
- [Табличный движок `Redis`](/engines/table-engines/integrations/redis.md)
-- [Использование Redis в качестве источника словаря](/sql-reference/dictionaries/index.md#redis)
+- [Использование Redis в качестве источника словаря](/sql-reference/statements/create/dictionary/sources#redis)
\ No newline at end of file
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/window-functions/index.md b/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/window-functions/index.md
index 7f09dc0b1e4..d6e3ab68567 100644
--- a/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/window-functions/index.md
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/sql-reference/window-functions/index.md
@@ -50,9 +50,13 @@ ClickHouse поддерживает стандартную грамматику
```text
aggregate_function (column_name)
OVER ([[PARTITION BY grouping_column] [ORDER BY sorting_column]
- [ROWS or RANGE expression_to_bound_rows_withing_the_group]] | [window_name])
+ [ROWS or RANGE expression_to_bound_rows_within_the_group]] | [window_name])
FROM table_name
-WINDOW window_name as ([[PARTITION BY grouping_column] [ORDER BY sorting_column]])
+WINDOW window_name as ([
+ [PARTITION BY grouping_column]
+ [ORDER BY sorting_column]
+ [ROWS or RANGE expression_to_bound_rows_within_the_group]
+])
```
* `PARTITION BY` - задает, как разбить результирующий набор на группы.
@@ -90,6 +94,7 @@ WINDOW window_name as ([[PARTITION BY grouping_column] [ORDER BY sorting_column]
* [`lagInFrame(x)`](./lagInFrame.md) - Возвращает значение, вычисленное для строки, которая находится на заданное количество строк раньше текущей строки в упорядоченном фрейме.
* [`leadInFrame(x)`](./leadInFrame.md) - Возвращает значение, вычисленное для строки, которая находится на заданное количество строк позже текущей строки в упорядоченном фрейме.
+
## Примеры \{#examples\}
Рассмотрим несколько примеров использования оконных функций.
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/tutorial.md b/i18n/ru/docusaurus-plugin-content-docs/current/tutorial.md
index f3c85babac7..24848faa927 100644
--- a/i18n/ru/docusaurus-plugin-content-docs/current/tutorial.md
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/tutorial.md
@@ -156,7 +156,7 @@ doc_type: 'guide'
Выполните несколько запросов для анализа данных. Изучите следующие примеры или попробуйте свой собственный SQL-запрос.
- * Вычислите средний размер чаевых:
+ * Рассчитайте среднюю сумму чаевых:
```sql
SELECT round(avg(tip_amount), 2) FROM trips
@@ -188,7 +188,7 @@ doc_type: 'guide'
Ожидаемый результат
- Значения `passenger_count` принимают значения от 0 до 9:
+ Поле `passenger_count` принимает значения от 0 до 9:
```response
┌─passenger_count─┬─average_total_amount─┐
@@ -238,7 +238,7 @@ doc_type: 'guide'
- * Вычислите продолжительность каждой поездки в минутах, затем сгруппируйте результаты по продолжительности поездки:
+ * Вычислите продолжительность каждой поездки в минутах, затем сгруппируйте результаты по длительности поездки:
```sql
SELECT
@@ -327,7 +327,7 @@ doc_type: 'guide'
- 7. Извлечь записи о поездках до аэропортов Ла‑Гуардия или JFK:
+ 7. Извлеките записи о поездках в аэропорты Ла‑Гуардия или JFK:
```sql
SELECT
@@ -369,7 +369,7 @@ doc_type: 'guide'
## Создайте словарь
- Словарь — это хранящееся в памяти отображение пар ключ-значение. Подробности см. в разделе [Словари](/sql-reference/dictionaries/index.md)
+ Словарь — это хранящееся в памяти отображение пар ключ-значение. Подробности см. в разделе [Словари](/sql-reference/statements/create/dictionary)
Создайте словарь, связанный с таблицей в вашем сервисе ClickHouse.
Таблица и словарь основаны на CSV-файле, который содержит строку для каждого района Нью-Йорка.
@@ -403,7 +403,7 @@ doc_type: 'guide'
```
:::note
- Установка `LIFETIME` в 0 отключает автоматические обновления, чтобы избежать ненужного трафика к нашему S3 бакету. В других случаях вы можете настроить это по‑другому. Подробности см. в разделе [Обновление данных словаря с помощью LIFETIME](/sql-reference/dictionaries#refreshing-dictionary-data-using-lifetime).
+ Установка `LIFETIME` в 0 отключает автоматические обновления, чтобы избежать ненужного трафика к нашему S3 бакету. В других случаях вы можете настроить это по‑другому. Подробности см. в разделе [Обновление данных словаря с помощью LIFETIME](/sql-reference/statements/create/dictionary/lifetime#refreshing-dictionary-data-using-lifetime).
:::
3. Убедитесь, что всё работает. Следующий запрос должен вернуть 265 строк — по одной для каждого района:
@@ -411,7 +411,7 @@ doc_type: 'guide'
SELECT * FROM taxi_zone_dictionary
```
- 4. Используйте функцию `dictGet` ([или ее варианты](./sql-reference/functions/ext-dict-functions.md)), чтобы извлечь значение из словаря. Вы передаете имя словаря, требуемое значение и ключ (в нашем примере это столбец `LocationID` словаря `taxi_zone_dictionary`).
+ 4. Используйте функцию `dictGet` ([или её варианты](./sql-reference/functions/ext-dict-functions.md)), чтобы извлечь значение из словаря. Вы передаёте имя словаря, значение, которое нужно получить, и ключ (в нашем примере это столбец `LocationID` словаря `taxi_zone_dictionary`).
Например, следующий запрос возвращает `Borough`, для которого `LocationID` равен 132, что соответствует аэропорту JFK):
@@ -429,12 +429,12 @@ doc_type: 'guide'
1 rows in set. Elapsed: 0.004 sec.
```
- 5. Используйте функцию `dictHas`, чтобы проверить, присутствует ли ключ в словаре. Например, следующий запрос возвращает `1` (в ClickHouse это означает «true»):
+ 5. Используйте функцию `dictHas`, чтобы проверить, присутствует ли ключ в словаре. Например, следующий запрос возвращает `1` (что соответствует значению «true» в ClickHouse):
```sql
SELECT dictHas('taxi_zone_dictionary', 132)
```
- 6. Следующий запрос вернёт 0, потому что 4567 не является значением поля `LocationID` в словаре:
+ 6. Следующий запрос вернёт 0, потому что 4567 не является значением `LocationID` в словаре:
```sql
SELECT dictHas('taxi_zone_dictionary', 4567)
```
@@ -484,7 +484,7 @@ doc_type: 'guide'
ORDER BY total DESC
```
- Ответ идентичен ответу на запрос `dictGet`:
+ Ответ идентичен результату запроса `dictGet`:
```response
┌─total─┬─Borough───────┐
@@ -514,7 +514,7 @@ doc_type: 'guide'
LIMIT 1000
```
:::note
- Как правило, в ClickHouse мы избегаем частого использования `SELECT *`. Следует извлекать только те столбцы, которые вам действительно нужны.
+ Как правило, в ClickHouse мы стараемся не использовать `SELECT *`. Рекомендуется извлекать только те столбцы, которые вам действительно нужны.
:::
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/use-cases/observability/build-your-own/schema-design.md b/i18n/ru/docusaurus-plugin-content-docs/current/use-cases/observability/build-your-own/schema-design.md
index df8f2b398d3..409d01bd826 100644
--- a/i18n/ru/docusaurus-plugin-content-docs/current/use-cases/observability/build-your-own/schema-design.md
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/use-cases/observability/build-your-own/schema-design.md
@@ -588,7 +588,7 @@ LIMIT 5
## Использование словарей \{#using-dictionaries\}
-[Словари](/sql-reference/dictionaries) — это [ключевая возможность](https://clickhouse.com/blog/faster-queries-dictionaries-clickhouse) ClickHouse, обеспечивающая хранимое в памяти представление данных в формате [key-value](https://en.wikipedia.org/wiki/Key%E2%80%93value_database) из различных внутренних и внешних [источников](/sql-reference/dictionaries#dictionary-sources), оптимизированное для сверхнизкой задержки при выполнении запросов поиска.
+[Словари](/sql-reference/statements/create/dictionary) — это [ключевая возможность](https://clickhouse.com/blog/faster-queries-dictionaries-clickhouse) ClickHouse, обеспечивающая хранимое в памяти представление данных в формате [key-value](https://en.wikipedia.org/wiki/Key%E2%80%93value_database) из различных внутренних и внешних [источников](/sql-reference/statements/create/dictionary/sources#dictionary-sources), оптимизированное для сверхнизкой задержки при выполнении запросов поиска.
@@ -726,7 +726,7 @@ SELECT
FROM geoip_url
```
-Чтобы выполнять низкозадержечные IP‑поиски в ClickHouse, мы будем использовать словари для хранения сопоставления ключей с атрибутами наших Geo IP‑данных в памяти. ClickHouse предоставляет структуру словаря `ip_trie` [структура словаря](/sql-reference/dictionaries#ip_trie) для сопоставления наших сетевых префиксов (CIDR‑блоков) с координатами и кодами стран. Следующий запрос определяет словарь, используя эту структуру и приведённую выше таблицу в качестве источника.
+Чтобы выполнять низкозадержечные IP‑поиски в ClickHouse, мы будем использовать словари для хранения сопоставления ключей с атрибутами наших Geo IP‑данных в памяти. ClickHouse предоставляет структуру словаря `ip_trie` [структура словаря](/sql-reference/statements/create/dictionary/layouts/ip-trie) для сопоставления наших сетевых префиксов (CIDR‑блоков) с координатами и кодами стран. Следующий запрос определяет словарь, используя эту структуру и приведённую выше таблицу в качестве источника.
```sql
CREATE DICTIONARY ip_trie (
@@ -838,10 +838,10 @@ ORDER BY (ServiceName, Timestamp)
Разбор [строк User-Agent](https://en.wikipedia.org/wiki/User_agent) — это классическая задача на регулярные выражения и типичное требование для наборов данных на основе логов и трассировок. ClickHouse обеспечивает эффективный разбор строк User-Agent с использованием Regular Expression Tree Dictionaries.
-Словари на основе дерева регулярных выражений определяются в ClickHouse open-source с использованием типа источника словаря YAMLRegExpTree, который указывает путь к YAML-файлу, содержащему дерево регулярных выражений. Если вы хотите использовать собственный словарь регулярных выражений, подробности о требуемой структуре можно найти [здесь](/sql-reference/dictionaries#use-regular-expression-tree-dictionary-in-clickhouse-open-source). Далее мы сосредоточимся на разборе User-Agent с использованием [uap-core](https://github.com/ua-parser/uap-core) и загрузим наш словарь в поддерживаемом формате CSV. Этот подход совместим как с OSS, так и с ClickHouse Cloud.
+Словари на основе дерева регулярных выражений определяются в ClickHouse open-source с использованием типа источника словаря YAMLRegExpTree, который указывает путь к YAML-файлу, содержащему дерево регулярных выражений. Если вы хотите использовать собственный словарь регулярных выражений, подробности о требуемой структуре можно найти [здесь](/sql-reference/statements/create/dictionary/layouts/regexp-tree#use-regular-expression-tree-dictionary-in-clickhouse-open-source). Далее мы сосредоточимся на разборе User-Agent с использованием [uap-core](https://github.com/ua-parser/uap-core) и загрузим наш словарь в поддерживаемом формате CSV. Этот подход совместим как с OSS, так и с ClickHouse Cloud.
:::note
-В примерах ниже мы используем снимки актуальных регулярных выражений uap-core для разбора User-Agent по состоянию на июнь 2024 года. Актуальный файл, который периодически обновляется, можно найти [здесь](https://raw.githubusercontent.com/ua-parser/uap-core/master/regexes.yaml). Вы можете выполнить шаги, описанные [здесь](/sql-reference/dictionaries#collecting-attribute-values), чтобы загрузить данные в CSV-файл, используемый ниже.
+В примерах ниже мы используем снимки актуальных регулярных выражений uap-core для разбора User-Agent по состоянию на июнь 2024 года. Актуальный файл, который периодически обновляется, можно найти [здесь](https://raw.githubusercontent.com/ua-parser/uap-core/master/regexes.yaml). Вы можете выполнить шаги, описанные [здесь](/sql-reference/statements/create/dictionary/layouts/regexp-tree#collecting-attribute-values), чтобы загрузить данные в CSV-файл, используемый ниже.
:::
Создайте следующие таблицы движка Memory. Они будут хранить наши регулярные выражения для разбора устройств, браузеров и операционных систем.
@@ -875,7 +875,7 @@ CREATE TABLE regexp_device
) ENGINE=Memory;
```
-Эти таблицы можно заполнить данными из следующих публично доступных CSV‑файлов с помощью табличной функции URL:
+Эти таблицы можно заполнить данными из следующих публично размещённых CSV‑файлов с помощью табличной функции url:
```sql
INSERT INTO regexp_os SELECT * FROM s3('https://datasets-documentation.s3.eu-west-3.amazonaws.com/user_agent_regex/regexp_os.csv', 'CSV', 'id UInt64, parent_id UInt64, regexp String, keys Array(String), values Array(String)')
@@ -1031,7 +1031,7 @@ Os: ('Other','0','0','0')
- [Расширенные темы по словарям](/dictionary#advanced-dictionary-topics)
- [«Использование словарей для ускорения запросов»](https://clickhouse.com/blog/faster-queries-dictionaries-clickhouse)
-- [Словари](/sql-reference/dictionaries)
+- [Словари](/sql-reference/statements/create/dictionary)
## Ускорение запросов \{#accelerating-queries\}
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/use-cases/observability/clickstack/alerts.md b/i18n/ru/docusaurus-plugin-content-docs/current/use-cases/observability/clickstack/alerts.md
index 3479706b659..a5843c63b87 100644
--- a/i18n/ru/docusaurus-plugin-content-docs/current/use-cases/observability/clickstack/alerts.md
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/use-cases/observability/clickstack/alerts.md
@@ -1,6 +1,6 @@
---
slug: /use-cases/observability/clickstack/alerts
-title: 'Поиск с ClickStack'
+title: 'Оповещения с ClickStack'
sidebar_label: 'Оповещения'
pagination_prev: null
pagination_next: null
@@ -24,15 +24,13 @@ import remove_chart_alert from '@site/static/images/use-cases/observability/remo
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
+ClickStack включает встроенную поддержку оповещений, позволяя командам в реальном времени обнаруживать и оперативно реагировать на проблемы в логах, метриках и трейсах.
-## Оповещения в ClickStack \{#alerting-in-clickstack\}
-
-ClickStack включает встроенную поддержку оповещений, позволяя командам в реальном времени выявлять проблемы в логах, метриках и трейсах и оперативно на них реагировать.
-
-Оповещения могут создаваться напрямую в интерфейсе HyperDX и интегрироваться с популярными системами уведомлений, такими как Slack и PagerDuty.
+Оповещения могут создаваться непосредственно в интерфейсе HyperDX и интегрироваться с популярными системами уведомлений, такими как Slack и PagerDuty.
Механизм оповещений бесшовно работает со всеми вашими данными в ClickStack, помогая отслеживать состояние системы, выявлять регрессии производительности и мониторить ключевые бизнес-события.
+
## Типы оповещений \{#types-of-alerts\}
ClickStack поддерживает два взаимодополняющих способа создания оповещений: **оповещения по поиску (Search alerts)** и **оповещения по графикам дашборда (Dashboard chart alerts)**. После создания оповещение привязывается либо к поисковому запросу, либо к графику.
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/use-cases/observability/clickstack/example-datasets/index.md b/i18n/ru/docusaurus-plugin-content-docs/current/use-cases/observability/clickstack/example-datasets/index.md
index 50cf5a70be8..c58ff43fe79 100644
--- a/i18n/ru/docusaurus-plugin-content-docs/current/use-cases/observability/clickstack/example-datasets/index.md
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/use-cases/observability/clickstack/example-datasets/index.md
@@ -14,4 +14,5 @@ keywords: ['Примеры наборов данных ClickStack', 'Демон
|---------|-------------|
| [Sample Data](sample-data.md) | Загрузите демонстрационный набор данных, содержащий логи, трейсы и метрики из нашего демонстрационного окружения |
| [Local Data](local-data.md) | Соберите метрики и логи локальной системы и отправьте их в ClickStack для анализа |
-| [Remote Demo Data](remote-demo-data.md) | Подключитесь к нашему удалённому демонстрационному кластеру и проанализируйте проблему |
\ No newline at end of file
+| [Remote Demo Data](remote-demo-data.md) | Подключитесь к нашему удалённому демонстрационному кластеру и проанализируйте проблему |
+| [Session Replay Demo](session-replay.md) | Настройте инструментацию демонстрационного веб-приложения для реплея сессий и просматривайте свои взаимодействия в ClickStack |
\ No newline at end of file
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/use-cases/observability/clickstack/example-datasets/session-replay.md b/i18n/ru/docusaurus-plugin-content-docs/current/use-cases/observability/clickstack/example-datasets/session-replay.md
new file mode 100644
index 00000000000..3e33206ba7e
--- /dev/null
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/use-cases/observability/clickstack/example-datasets/session-replay.md
@@ -0,0 +1,179 @@
+---
+slug: /use-cases/observability/clickstack/example-datasets/session-replay-demo
+title: 'Демонстрация воспроизведения сессий'
+sidebar_position: 4
+pagination_prev: null
+pagination_next: null
+description: 'Интерактивное демонстрационное приложение, показывающее, как настроить инструментирование веб-приложения для воспроизведения сессий в ClickStack'
+doc_type: 'guide'
+keywords: ['clickstack', 'воспроизведение сессий', 'браузерный SDK', 'демо', 'обсервабилити', 'инструментирование']
+---
+
+import Image from '@theme/IdealImage';
+import api_key from '@site/static/images/clickstack/api-key.png';
+import demo_app from '@site/static/images/clickstack/session-replay/demo-app.png';
+import session_replay from '@site/static/images/clickstack/session-replay/session-replay.png';
+import replay_search from '@site/static/images/clickstack/session-replay/replay-search-view.png';
+
+:::note[Если кратко]
+В этом руководстве описывается процесс инструментирования веб-приложения для записи и воспроизведения сессий с помощью ClickStack Browser SDK. В отличие от других демонстрационных наборов данных, которые загружают заранее сгенерированные данные, это демо предоставляет интерактивное приложение, в котором вы генерируете данные сессий своими действиями.
+
+Ориентировочное время: 10–15 минут
+:::
+
+
+## Обзор \{#overview\}
+
+[Демонстрационное приложение для session replay](https://github.com/ClickHouse/clickstack-session-replay-demo) — это просмотрщик документации, написанный на чистом JavaScript. Оно демонстрирует, насколько минимальным может быть инструментирование session replay: один тег со скриптом и один вызов инициализации автоматически фиксируют все действия пользователя.
+
+Репозиторий содержит две ветки:
+
+- **`main`** — полностью инструментированная и готовая к немедленному использованию
+- **`pre-instrumented`** — чистая версия без инструментирования, с комментариями в коде, указывающими, где его добавить
+
+В этом руководстве сначала используется ветка `main`, чтобы увидеть session replay в действии, а затем подробно рассматривается код инструментирования, чтобы вы могли применить тот же подход в своём приложении.
+
+Для ознакомления с тем, что такое session replay и как он интегрируется в ClickStack, см. страницу функции [Session Replay](/use-cases/observability/clickstack/session-replay).
+
+## Предварительные требования \{#prerequisites\}
+
+- Установлены Docker и Docker Compose
+- Порты 3000, 4317, 4318 и 8080 должны быть свободны
+
+## Запуск демо \{#running-the-demo\}
+
+
+
+### Клонирование репозитория \{#clone-repository\}
+
+```shell
+git clone https://github.com/ClickHouse/clickstack-session-replay-demo
+cd clickstack-session-replay-demo
+```
+
+### Запуск ClickStack \{#start-clickstack\}
+
+```shell
+docker-compose up -d clickstack
+```
+
+### Получение вашего ключа API \{#get-api-key\}
+
+1. Откройте HyperDX по адресу [http://localhost:8080](http://localhost:8080)
+2. Создайте аккаунт или войдите, если он уже есть
+3. Перейдите в **Team Settings → API Keys**
+4. Скопируйте ваш **ключ API для приёма данных API key**
+
+
+
+5. Установите его как переменную окружения:
+
+```shell
+export CLICKSTACK_API_KEY='your-api-key-here'
+```
+
+### Запуск демонстрационного приложения \{#start-demo-app\}
+
+```shell
+docker-compose --profile demo up demo-app
+```
+
+:::note
+Убедитесь, что вы выполняете эту команду в том же терминале, в котором экспортировали переменную `CLICKSTACK_API_KEY`.
+:::
+
+Откройте [http://localhost:3000](http://localhost:3000) в браузере и взаимодействуйте с приложением: ищите темы, фильтруйте по категориям, просматривайте примеры кода и добавляйте элементы в закладки.
+
+
+
+Все взаимодействия автоматически записываются ClickStack Browser SDK.
+
+### Просмотр воспроизведения вашей сессии \{#view-session-replay\}
+
+Вернитесь в HyperDX по адресу [http://localhost:8080](http://localhost:8080) и перейдите в раздел **Client Sessions** в левой боковой панели.
+
+
+
+Вы должны увидеть свою сессию с указанием её продолжительности и количества событий. Нажмите кнопку ▶️, чтобы воспроизвести её.
+
+
+
+Переключайтесь между режимами **Highlighted** и **All Events**, чтобы настроить уровень детализации на временной шкале.
+
+
+
+## Инструментирование \{#instrumentation\}
+
+Демонстрационное приложение показывает, как мало кода требуется для включения воспроизведения сессий (session replay). Достаточно всего двух изменений в приложении:
+
+**1. Подключите SDK (`app/public/index.html`):**
+
+```html
+
+```
+
+**2. Инициализируйте ClickStack (`app/public/js/app.js`):**
+
+```javascript
+window.HyperDX.init({
+ url: 'http://localhost:4318',
+ apiKey: window.CLICKSTACK_API_KEY,
+ service: 'clickhouse-session-replay-demo',
+ consoleCapture: true,
+ advancedNetworkCapture: true,
+});
+```
+
+Остальной код — это стандартный прикладной код. SDK автоматически собирает все взаимодействия пользователя, логи консоли, сетевые запросы и ошибки — дополнительная инструментация не требуется.
+
+
+### Попробуйте сами \{#try-it-yourself\}
+
+Чтобы инструментировать приложение с нуля, переключитесь на ветку `pre-instrumented`:
+
+```shell
+git checkout pre-instrumented
+```
+
+Эта ветка содержит то же приложение, но без какого-либо инструментирования ClickStack. Комментарии в коде в `app/public/index.html` и `app/public/js/app.js` указывают, куда именно нужно добавить два приведённых выше фрагмента кода. После добавления перезапустите демонстрационное приложение, и ваши взаимодействия начнут отображаться в ClickStack.
+
+
+## Устранение неполадок \{#troubleshooting\}
+
+### Сеансы не отображаются в HyperDX \{#sessions-not-appearing\}
+
+1. Проверьте консоль браузера на наличие ошибок
+2. Убедитесь, что ClickStack запущён: `docker-compose ps`
+3. Убедитесь, что установлен API-ключ: `echo $CLICKSTACK_API_KEY`
+4. Измените временной диапазон в представлении Client Sessions (попробуйте **Last 15 minutes**)
+5. Выполните принудительное обновление страницы в браузере: `Cmd+Shift+R` (Mac) или `Ctrl+Shift+R` (Windows/Linux)
+
+### Ошибки 401 Unauthorized \{#401-errors\}
+
+API-ключ указан некорректно. Убедитесь, что вы:
+
+1. Экспортировали его в терминале: `export CLICKSTACK_API_KEY='your-key'`
+2. Запустили демо-приложение в **том же терминале**, где вы его экспортировали
+3. Получили ключ в интерфейсе HyperDX (а не использовали случайно сгенерированную строку)
+
+## Очистка \{#cleanup\}
+
+Остановите сервисы:
+
+```bash
+docker-compose down
+```
+
+Удалить все данные:
+
+```bash
+docker-compose down -v
+```
+
+
+## Подробнее \{#learn-more\}
+
+- [Session Replay](/use-cases/observability/clickstack/session-replay) — обзор функции, варианты SDK и настройки конфиденциальности
+- [Browser SDK Reference](/use-cases/observability/clickstack/sdks/browser) — полный перечень возможностей SDK и расширенные настройки
+- [ClickStack Getting Started](/use-cases/observability/clickstack/getting-started) — разверните ClickStack и выполните приём ваших первых данных
+- [All Sample Datasets](/use-cases/observability/clickstack/sample-datasets) — другие примерные наборы данных и руководства
\ No newline at end of file
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/use-cases/observability/clickstack/session-replay.md b/i18n/ru/docusaurus-plugin-content-docs/current/use-cases/observability/clickstack/session-replay.md
new file mode 100644
index 00000000000..2d6032f235c
--- /dev/null
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/use-cases/observability/clickstack/session-replay.md
@@ -0,0 +1,150 @@
+---
+slug: /use-cases/observability/clickstack/session-replay
+title: "Воспроизведение сессий"
+sidebar_label: "Воспроизведение сессий"
+sidebar_position: 5
+pagination_prev: null
+pagination_next: null
+description: "Записывайте и воспроизводите пользовательские сессии в ClickStack, чтобы отлаживать проблемы фронтенда, понимать поведение пользователей и коррелировать активность браузера с логами и трейсами на бэкенде."
+doc_type: 'guide'
+keywords: ['clickstack', 'воспроизведение сессий', 'браузерный SDK', 'обсервабилити фронтенда', 'пользовательские сессии', 'отладка']
+---
+
+import Image from '@theme/IdealImage';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import session_replay from '@site/static/images/clickstack/session-replay/session-replay.png';
+import replay_search from '@site/static/images/clickstack/session-replay/replay-search-view.png';
+import trace_to_replay from '@site/static/images/clickstack/session-replay/trace-to-replay.png';
+import clickpy_trace from '@site/static/images/clickstack/session-replay/clickpy-trace.gif';
+
+Воспроизведение сессий в ClickStack захватывает и воссоздаёт взаимодействия пользователей с вашим веб-приложением, позволяя визуально воспроизвести в точности то, что пользователь видел и делал во время своей сессии. Вместо видеозаписи SDK фиксирует изменения DOM, движения мыши, клики, прокрутку, ввод с клавиатуры, логи консоли, сетевые запросы (XHR, Fetch, WebSocket) и исключения JavaScript, а затем воссоздаёт этот пользовательский опыт в браузере.
+
+Поскольку воспроизведения сессий хранятся в ClickHouse вместе с логами, трейcами и метриками, вы можете за несколько кликов перейти от просмотра пользовательского опыта к анализу бэкенд-трейсов и запросов к базе данных, которые за ним стоят. Это делает воспроизведение сессий полезным для отладки проблем в продакшене, понимания поведения пользователей, выявления точек трения в UX и визуального подтверждения инцидентов, о которых сообщают в поддержку.
+
+
+## Инструментирование вашего приложения \{#instrumentation\}
+
+ClickStack полностью совместим с OpenTelemetry, поэтому вы можете отправлять браузерную телеметрию (трейсы, исключения) с помощью стандартного JavaScript SDK OpenTelemetry или любого из [языковых SDK ClickStack](/use-cases/observability/clickstack/sdks). Однако **для session replay требуется ClickStack Browser SDK** (`@hyperdx/browser`), который расширяет OpenTelemetry SDK возможностями записи сессий, захвата консоли и сетевых запросов. Если вам нужны только трейсы без session replay, любой совместимый с OTel браузерный SDK будет работать с ClickStack.
+
+Примеры ниже используют ClickStack Browser SDK. Добавление session replay в ваше приложение включает всего три шага: установка пакета, инициализация SDK, после чего все действия пользователя автоматически записываются — дополнительные изменения в коде не требуются.
+
+:::tip
+Инициализируйте SDK в месте, которое гарантированно загружается при старте вашего приложения. Например, в приложении Next.js это может быть корневой `layout.js`. Это обеспечивает немедленный запуск записи сессий и захват полного пользовательского опыта.
+:::
+
+
+
+
+```shell
+npm install @hyperdx/browser
+```
+
+```javascript
+import HyperDX from '@hyperdx/browser';
+
+HyperDX.init({
+ url: 'http://your-otel-collector:4318',
+ apiKey: 'YOUR_INGESTION_API_KEY', // не указывайте для Managed ClickStack
+ service: 'my-frontend-app',
+ tracePropagationTargets: [/api.myapp.domain/i],
+ consoleCapture: true,
+ advancedNetworkCapture: true,
+});
+```
+
+
+
+
+```shell
+yarn add @hyperdx/browser
+```
+
+```javascript
+import HyperDX from '@hyperdx/browser';
+
+HyperDX.init({
+ url: 'http://your-otel-collector:4318',
+ apiKey: 'YOUR_INGESTION_API_KEY', // не указывайте для Managed ClickStack
+ service: 'my-frontend-app',
+ tracePropagationTargets: [/api.myapp.domain/i],
+ consoleCapture: true,
+ advancedNetworkCapture: true,
+});
+```
+
+
+
+
+Для приложений, не использующих бандлер, подключите SDK напрямую через тег script. Это создаст глобальную переменную `HyperDX`, которую можно использовать так же, как пакет NPM.
+
+```html
+
+
+```
+
+
+
+
+:::note
+Опция `tracePropagationTargets` ключевая для связывания session replay с бэкенд-трейсами — укажите здесь домен вашего API, чтобы включить полноценный распределённый трейсинг от фронтенда до бэкенда. Полный список опций SDK, включая настройки конфиденциальности, кастомные действия, React error boundaries и source maps, приведён в [справочнике по Browser SDK](/use-cases/observability/clickstack/sdks/browser).
+:::
+
+Browser SDK также поддерживает [маскирование инпутов и текста](/use-cases/observability/clickstack/sdks/browser#options) для приложений с повышенными требованиями к конфиденциальности, а также [привязку информации о пользователе](/use-cases/observability/clickstack/sdks/browser#attach-user-information-or-metadata), чтобы вы могли искать и фильтровать сессии по пользователю в интерфейсе ClickStack.
+
+## Просмотр реплеев сессий \{#viewing-replays\}
+
+Перейдите в раздел **Client Sessions** на левой боковой панели в интерфейсе ClickStack (HyperDX). В этом представлении перечислены все записанные браузерные сессии с указанием их длительности и количества событий.
+
+
+
+Нажмите кнопку воспроизведения у любой сессии, чтобы просмотреть её реплей. В представлении реплея реконструированный пользовательский опыт отображается справа, а таймлайн браузерных событий — сетевых запросов, логов консоли и ошибок — слева.
+
+
+
+Переключайтесь между режимами **Highlighted** и **All Events**, чтобы настроить уровень детализации, отображаемый на таймлайне. Ошибки помечаются красным цветом, а при клике на любое событие реплей переходит к соответствующему моменту сессии.
+
+### От сессии к трейсу \{#session-to-trace\}
+
+Когда вы выбираете сетевой запрос или ошибку на таймлайне сессии, вы можете перейти на вкладку **Trace**, чтобы отследить этот запрос через ваши backend-сервисы — просматривая связанные логи, спаны и запросы к базе данных, которые были вызваны этим действием пользователя.
+
+Это работает, так как конфигурация `tracePropagationTargets` связывает спаны браузера со спанами сервера через заголовок `traceparent`, формируя единый распределённый трейc от клика пользователя до самой базы данных. Подробный пошаговый разбор этого на практике, включая инструментирование как frontend-, так и backend-частей, см. в статье [Instrumenting your NextJS application with OpenTelemetry and ClickStack](https://clickhouse.com/blog/instrumenting-nextjs-opentelemetry-clickstack).
+
+
+
+### От трассы к сессии \{#trace-to-session\}
+
+Корреляция работает и в обратном направлении. При просмотре трассы в представлении **Search** щёлкните на неё, чтобы открыть подробную информацию о трассе, затем выберите вкладку **Session Replay**, чтобы увидеть, что именно видел и делал пользователь в момент формирования этой трассы. Это особенно полезно при расследовании ошибок или медленных запросов — вы можете начать с проблемы на стороне бэкенда и сразу увидеть, как происходящее выглядело для пользователя.
+
+
+
+## Как хранятся данные сессии \{#data-storage\}
+
+Данные для воспроизведения сессий хранятся в отдельной таблице [`hyperdx_sessions`](/use-cases/observability/clickstack/ingesting-data/schemas#sessions) в ClickHouse, отдельно от логов и трейсов. Каждое событие сессии — это строка с полем `Body`, содержащим полезную нагрузку события, и отображением `LogAttributes`, в котором хранятся метаданные события. Столбцы `Body` и `LogAttributes` вместе содержат детали реальных событий сессии, которые используются для восстановления воспроизведения.
+
+Полную информацию о схеме таблицы см. в разделе [Таблицы и схемы, используемые ClickStack](/use-cases/observability/clickstack/ingesting-data/schemas).
+
+## Попробуйте на практике \{#try-it-out\}
+
+Есть два способа увидеть session replay в действии:
+
+- **Живой пример** — перейдите на [clickpy.clickhouse.com](https://clickpy.clickhouse.com), повзаимодействуйте с приложением, затем посмотрите запись своей сессии на [play-clickstack.clickhouse.com](https://play-clickstack.clickhouse.com) в источнике **ClickPy Sessions**. Подробности об инструментации ClickPy см. в записи в блоге [Instrumenting your NextJS application with OpenTelemetry and ClickStack](https://clickhouse.com/blog/instrumenting-your-app-with-otel-clickstack).
+- **Локальный демонстрационный пример** — [Session Replay Demo](/use-cases/observability/clickstack/example-datasets/session-replay-demo) пошагово показывает, как проинструментировать демонстрационное приложение, включая локальный запуск ClickStack и просмотр записей сессий.
+
+## Узнать больше \{#learn-more\}
+
+- [Демонстрация Session Replay](/use-cases/observability/clickstack/example-datasets/session-replay-demo) — интерактивное локальное демо‑приложение с пошаговыми инструкциями
+- [Справочник по Browser SDK](/use-cases/observability/clickstack/sdks/browser) — все варианты конфигурации SDK, source maps, пользовательские действия и расширенные настройки
+- [Поиск](/use-cases/observability/clickstack/search) — синтаксис поиска для фильтрации сессий и событий
+- [Дашборды](/use-cases/observability/clickstack/dashboards) — создание визуализаций и дашбордов на основе данных сессий и трассировок
+- [Оповещения](/use-cases/observability/clickstack/alerts) — настройка оповещений по ошибкам, задержкам и другим сигналам
+- [Архитектура ClickStack](/use-cases/observability/clickstack/architecture) — как ClickHouse, HyperDX и OTel collector интегрируются друг с другом
\ No newline at end of file
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/whats-new/roadmap.md b/i18n/ru/docusaurus-plugin-content-docs/current/whats-new/roadmap.md
index 3ce12473045..2e90e211547 100644
--- a/i18n/ru/docusaurus-plugin-content-docs/current/whats-new/roadmap.md
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/whats-new/roadmap.md
@@ -7,22 +7,19 @@ doc_type: 'landing-page'
keywords: ['дорожная карта', 'будущие возможности', 'планы разработки', 'предстоящие релизы', 'направление развития продукта']
---
-
-
## Текущая дорожная карта \{#current-roadmap\}
Текущая дорожная карта доступна для открытого обсуждения:
-- [2025](https://github.com/ClickHouse/ClickHouse/issues/74046)
-
-
+- [2026](https://github.com/ClickHouse/ClickHouse/issues/93288)
## Предыдущие дорожные карты \{#previous-roadmaps\}
+- [2025](https://github.com/ClickHouse/ClickHouse/issues/74046)
- [2024](https://github.com/ClickHouse/ClickHouse/issues/58392)
- [2023](https://github.com/ClickHouse/ClickHouse/issues/44767)
- [2022](https://github.com/ClickHouse/ClickHouse/issues/44767)
- [2021](https://github.com/ClickHouse/ClickHouse/issues/17623)
- [2020](https://github.com/ClickHouse/ClickHouse/blob/be29057de1835f6f4a17e03a422b45b81efe6833/docs/ru/whats-new/extended-roadmap.md)
- [2019](https://github.com/ClickHouse/ClickHouse/issues/4785)
-- [2018](https://presentations.clickhouse.com/?path=2018-roadmap)
+- [2018](https://presentations.clickhouse.com/?path=2018-roadmap)
\ No newline at end of file
diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/about-us/beta-and-experimental-features.md b/i18n/zh/docusaurus-plugin-content-docs/current/about-us/beta-and-experimental-features.md
index 6d01ecb9b0e..c8895e1a2ea 100644
--- a/i18n/zh/docusaurus-plugin-content-docs/current/about-us/beta-and-experimental-features.md
+++ b/i18n/zh/docusaurus-plugin-content-docs/current/about-us/beta-and-experimental-features.md
@@ -68,7 +68,6 @@ doc_type: 'reference'
| [allow_statistics_optimize](/operations/settings/settings#allow_statistics_optimize) | `1` |
| [use_statistics](/operations/settings/settings#use_statistics) | `1` |
| [use_statistics_cache](/operations/settings/settings#use_statistics_cache) | `1` |
-| [enable_full_text_index](/operations/settings/settings#enable_full_text_index) | `1` |
| [allow_experimental_delta_kernel_rs](/operations/settings/settings#allow_experimental_delta_kernel_rs) | `1` |
| [allow_insert_into_iceberg](/operations/settings/settings#allow_insert_into_iceberg) | `0` |
| [enable_join_runtime_filters](/operations/settings/settings#enable_join_runtime_filters) | `1` |
@@ -94,6 +93,9 @@ doc_type: 'reference'
| [remote_fs_zero_copy_zookeeper_path](/operations/settings/merge-tree-settings#remote_fs_zero_copy_zookeeper_path) | `/clickhouse/zero_copy` |
| [remove_rolled_back_parts_immediately](/operations/settings/merge-tree-settings#remove_rolled_back_parts_immediately) | `1` |
| [shared_merge_tree_virtual_parts_discovery_batch](/operations/settings/merge-tree-settings#shared_merge_tree_virtual_parts_discovery_batch) | `1` |
+| [ast_fuzzer_runs](/operations/settings/settings#ast_fuzzer_runs) | `0` |
+| [ast_fuzzer_any_query](/operations/settings/settings#ast_fuzzer_any_query) | `0` |
+| [allow_fuzz_query_functions](/operations/settings/settings#allow_fuzz_query_functions) | `0` |
| [allow_experimental_kafka_offsets_storage_in_keeper](/operations/settings/settings#allow_experimental_kafka_offsets_storage_in_keeper) | `0` |
| [allow_experimental_delta_lake_writes](/operations/settings/settings#allow_experimental_delta_lake_writes) | `0` |
| [automatic_parallel_replicas_mode](/operations/settings/settings#automatic_parallel_replicas_mode) | `0` |
diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/cloud/guides/infrastructure/01_deployment_options/byoc/01_overview.md b/i18n/zh/docusaurus-plugin-content-docs/current/cloud/guides/infrastructure/01_deployment_options/byoc/01_overview.md
index 39c2f7773d1..9c6902ffdd4 100644
--- a/i18n/zh/docusaurus-plugin-content-docs/current/cloud/guides/infrastructure/01_deployment_options/byoc/01_overview.md
+++ b/i18n/zh/docusaurus-plugin-content-docs/current/cloud/guides/infrastructure/01_deployment_options/byoc/01_overview.md
@@ -27,7 +27,7 @@ BYOC 专为大规模部署设计,并要求客户签署具有使用承诺的合
* AWS(GA)
* GCP(Private Preview)。如果您感兴趣,请在[此处](https://clickhouse.com/cloud/bring-your-own-cloud)加入候补名单。
-* Azure(Roadmap)。如果您感兴趣,请在[此处](https://clickhouse.com/cloud/bring-your-own-cloud)加入候补名单。
+* Azure(Private Preview)。如果您感兴趣,请在[此处](https://clickhouse.com/cloud/bring-your-own-cloud)加入候补名单。
**支持的云区域:**
在我们的[支持的区域](https://clickhouse.com/docs/cloud/reference/supported-regions)文档中列出的所有**公共区域**均可用于 BYOC 部署。目前不支持私有区域。
diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/cloud/onboard/02_migrate/01_migration_guides/08_other_methods/01_clickhouse-local-etl.md b/i18n/zh/docusaurus-plugin-content-docs/current/cloud/onboard/02_migrate/01_migration_guides/08_other_methods/01_clickhouse-local-etl.md
index da0c3f392ce..2c58a73ceed 100644
--- a/i18n/zh/docusaurus-plugin-content-docs/current/cloud/onboard/02_migrate/01_migration_guides/08_other_methods/01_clickhouse-local-etl.md
+++ b/i18n/zh/docusaurus-plugin-content-docs/current/cloud/onboard/02_migrate/01_migration_guides/08_other_methods/01_clickhouse-local-etl.md
@@ -84,7 +84,7 @@ ClickHouse 为 [MySQL](/engines/table-engines/integrations/mysql/)、[PostgreSQL
-## 示例 1:使用 Integration 表引擎从 MySQL 迁移到 ClickHouse Cloud \{#example-1-migrating-from-mysql-to-clickhouse-cloud-with-an-integration-engine\}
+## 示例:使用 Integration 表引擎从 MySQL 迁移到 ClickHouse Cloud \{#example-1-migrating-from-mysql-to-clickhouse-cloud-with-an-integration-engine\}
我们将使用 [integration 表引擎](/engines/table-engines/integrations/mysql/)(由 [mysql 表函数](/sql-reference/table-functions/mysql/) 动态创建)从源 MySQL 数据库读取数据,并使用 [remoteSecure 表函数](/sql-reference/table-functions/remote/) 将数据写入您在 ClickHouse Cloud 服务中的目标表。
@@ -121,19 +121,4 @@ SELECT * FROM mysql('host:port', 'database', 'table', 'user', 'password');"
:::note
在 `clickhouse-local` 主机本地不会存储任何数据。相反,数据会从源 MySQL 表中读取,然后立即写入 ClickHouse Cloud 服务上的目标表。
-:::
-
-## 示例 2:使用 JDBC Bridge 将 MySQL 迁移到 ClickHouse Cloud \{#example-2-migrating-from-mysql-to-clickhouse-cloud-with-the-jdbc-bridge\}
-
-我们将使用 [JDBC 集成表引擎](/engines/table-engines/integrations/jdbc.md)(由 [jdbc 表函数](/sql-reference/table-functions/jdbc.md) 动态创建),配合 [ClickHouse JDBC Bridge](https://github.com/ClickHouse/clickhouse-jdbc-bridge) 和 MySQL JDBC 驱动,从源 MySQL 数据库中读取数据,并使用 [remoteSecure 表函数](/sql-reference/table-functions/remote.md)
-将数据写入 ClickHouse Cloud 服务中的目标表。
-
-
-
-### 在目标 ClickHouse Cloud 服务中: \{#on-the-destination-clickhouse-cloud-service-1\}
-
-#### 创建目标数据库: \{#create-the-destination-database-1\}
-
-```sql
- CREATE DATABASE db
- ```
+:::
\ No newline at end of file
diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/cloud/reference/01_changelog/01_changelog.md b/i18n/zh/docusaurus-plugin-content-docs/current/cloud/reference/01_changelog/01_changelog.md
index 286d80eb6a9..fb376bcc182 100644
--- a/i18n/zh/docusaurus-plugin-content-docs/current/cloud/reference/01_changelog/01_changelog.md
+++ b/i18n/zh/docusaurus-plugin-content-docs/current/cloud/reference/01_changelog/01_changelog.md
@@ -43,6 +43,10 @@ import crash_reports_collection from '@site/static/images/cloud/reference/crash-
:::
+## 2026 年 2 月 20 日 \{#february-20-2026\}
+
+- **ClickPipes:** 处于非活动状态的反向私有终端节点现在会在经过指定的宽限期后自动删除。这样可以确保未使用或配置错误的终端节点不会在后端系统中被无限期保留。更多详情请参阅自动清理[文档](/integrations/clickpipes/aws-privatelink#automatic-cleanup)。
+
## 2026 年 2 月 13 日 \{#february-13-2026\}
- [BigQuery Connector](/integrations/clickpipes/bigquery/overview) 现已进入私有预览阶段。阅读这篇[博客文章](https://clickhouse.com/blog/bigquery-clickpipe-private-preview)了解更多详情,并加入[候补名单](https://clickhouse.com/cloud/clickpipes/bigquery-connector)以申请访问权限。
@@ -1584,7 +1588,7 @@ ClickHouse Cloud 现已达到生产级就绪状态,具备 SOC2 Type II 合规
### 常规更改 \{#general-changes-5\}
-- 新增对基于本地 ClickHouse 表和 HTTP 源的 [dictionaries](/sql-reference/dictionaries/index.md) 的支持
+- 新增对基于本地 ClickHouse 表和 HTTP 源的 [dictionaries](/sql-reference/statements/create/dictionary) 的支持
- 引入了对孟买 [region](/cloud/reference/supported-regions) 的支持
### 控制台更改 \{#console-changes-30\}
diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/dictionary/index.md b/i18n/zh/docusaurus-plugin-content-docs/current/dictionary/index.md
index 567ff94ecdd..c82d7167e94 100644
--- a/i18n/zh/docusaurus-plugin-content-docs/current/dictionary/index.md
+++ b/i18n/zh/docusaurus-plugin-content-docs/current/dictionary/index.md
@@ -3,16 +3,17 @@ slug: /dictionary
title: '字典'
keywords: ['dictionary', 'dictionaries']
description: '字典以键值对形式表示数据,以支持快速查找。'
-doc_type: 'reference'
+doc_type: 'guide'
---
import dictionaryUseCases from '@site/static/images/dictionary/dictionary-use-cases.png';
import dictionaryLeftAnyJoin from '@site/static/images/dictionary/dictionary-left-any-join.png';
import Image from '@theme/IdealImage';
+
# 字典 \{#dictionary\}
-ClickHouse 中的字典以内存中的 [key-value](https://en.wikipedia.org/wiki/Key%E2%80%93value_database) 形式表示来自各种[内部和外部数据源](/sql-reference/dictionaries#dictionary-sources)的数据,并针对超低延迟的查找查询进行了优化。
+ClickHouse 中的字典以内存中的 [key-value](https://en.wikipedia.org/wiki/Key%E2%80%93value_database) 形式表示来自各种[内部和外部数据源](/sql-reference/statements/create/dictionary/sources#dictionary-sources)的数据,并针对超低延迟的查找查询进行了优化。
字典可用于:
@@ -87,7 +88,7 @@ Controversial_ratio: 0
#### 应用字典 \{#applying-a-dictionary\}
-为了演示这些概念,我们为投票数据使用一个字典。由于字典通常存放在内存中([ssd_cache](/sql-reference/dictionaries#ssd_cache) 是一个例外),你应当注意数据的大小。先确认一下我们的 `votes` 表的大小:
+为了演示这些概念,我们为投票数据使用一个字典。由于字典通常存放在内存中([ssd_cache](/sql-reference/statements/create/dictionary/layouts/ssd-cache) 是一个例外),你应当注意数据的大小。先确认一下我们的 `votes` 表的大小:
```sql
SELECT table,
@@ -105,7 +106,7 @@ GROUP BY table
数据将在我们的字典中以未压缩形式存储,因此如果要将所有列(实际上我们不会这样做)都存入字典,至少需要 4GB 内存。字典会在集群中进行复制,因此这部分内存需要 *按节点* 预留。
-> 在下面的示例中,我们字典的数据来源于一个 ClickHouse 表。虽然这是字典最常见的数据源,但还支持[多种数据源](/sql-reference/dictionaries#dictionary-sources),包括文件、HTTP 以及包括 [Postgres](/sql-reference/dictionaries#postgresql) 在内的各类数据库。正如我们将展示的那样,字典可以自动刷新,为小型且经常变更的数据集提供了一种理想方式,使其可用于直接进行 join 操作。
+> 在下面的示例中,我们字典的数据来源于一个 ClickHouse 表。虽然这是字典最常见的数据源,但还支持[多种数据源](/sql-reference/statements/create/dictionary/sources#dictionary-sources),包括文件、HTTP 以及包括 [Postgres](/sql-reference/statements/create/dictionary/sources/postgresql) 在内的各类数据库。正如我们将展示的那样,字典可以自动刷新,为小型且经常变更的数据集提供了一种理想方式,使其可用于直接进行 join 操作。
我们的字典需要一个用于执行查找的主键。这在概念上与事务型数据库中的主键相同,并且必须唯一。上面的查询需要在 join 键 `PostId` 上执行查找。字典应相应地填充为来自 `votes` 表的每个 `PostId` 的赞成票和反对票总数。下面是获取该字典数据的查询:
@@ -117,7 +118,7 @@ FROM votes
GROUP BY PostId
```
-要创建该字典,我们需要使用以下 DDL——注意其中使用了上面的查询:
+要创建该字典,需要使用以下 DDL——注意其中使用了上面的查询:
```sql
CREATE DICTIONARY votes_dict
@@ -319,20 +320,20 @@ Peak memory usage: 666.82 MiB.
### 选择字典 `LAYOUT` \{#choosing-the-dictionary-layout\}
-`LAYOUT` 子句控制字典的内部数据结构。有多种可用选项,其文档见[此处](/sql-reference/dictionaries#ways-to-store-dictionaries-in-memory)。关于如何选择合适布局的一些建议见[这里](https://clickhouse.com/blog/faster-queries-dictionaries-clickhouse#choosing-a-layout)。
+`LAYOUT` 子句控制字典的内部数据结构。有多种可用选项,其文档见[此处](/sql-reference/statements/create/dictionary/layouts#ways-to-store-dictionaries-in-memory)。关于如何选择合适布局的一些建议见[这里](https://clickhouse.com/blog/faster-queries-dictionaries-clickhouse#choosing-a-layout)。
### 刷新字典 \{#refreshing-dictionaries\}
我们为字典指定了 `LIFETIME MIN 600 MAX 900`。`LIFETIME` 用于控制字典的更新间隔,上述取值会使字典在 600 到 900 秒之间的随机时间间隔内周期性地重新加载。这个随机间隔是必要的,以便在大量服务器进行更新时分散对字典数据源的负载。在更新过程中,旧版本的字典仍然可以被查询,只有初始加载时才会阻塞查询。注意,将 `LIFETIME(0)` 进行设置会禁止字典更新。
可以使用 `SYSTEM RELOAD DICTIONARY` 命令强制重新加载字典。
-对于 ClickHouse 和 Postgres 等数据库数据源,你可以设置一个查询,仅在字典数据确实发生变化时才更新字典(由该查询的响应来决定),而不是按固定周期更新。更多详细信息请参见[此处](/sql-reference/dictionaries#refreshing-dictionary-data-using-lifetime)。
+对于 ClickHouse 和 Postgres 等数据库数据源,你可以设置一个查询,仅在字典数据确实发生变化时才更新字典(由该查询的响应来决定),而不是按固定周期更新。更多详细信息请参见[此处](/sql-reference/statements/create/dictionary/lifetime#refreshing-dictionary-data-using-lifetime)。
### 其他字典类型 \{#other-dictionary-types\}
-ClickHouse 还支持[层次结构字典](/sql-reference/dictionaries#hierarchical-dictionaries)、[多边形字典](/sql-reference/dictionaries#polygon-dictionaries)和[正则表达式字典](/sql-reference/dictionaries#regexp-tree-dictionary)。
+ClickHouse 还支持[层次结构字典](/sql-reference/statements/create/dictionary/layouts/hierarchical)、[多边形字典](/sql-reference/statements/create/dictionary/layouts/polygon)和[正则表达式字典](/sql-reference/statements/create/dictionary/layouts/regexp-tree)。
### 延伸阅读 \{#more-reading\}
- [使用字典加速查询](https://clickhouse.com/blog/faster-queries-dictionaries-clickhouse)
-- [字典的高级配置](/sql-reference/dictionaries)
\ No newline at end of file
+- [字典的高级配置](/sql-reference/statements/create/dictionary)
\ No newline at end of file
diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/engines/table-engines/integrations/iceberg.md b/i18n/zh/docusaurus-plugin-content-docs/current/engines/table-engines/integrations/iceberg.md
index cd8cd5ed100..975e734f65e 100644
--- a/i18n/zh/docusaurus-plugin-content-docs/current/engines/table-engines/integrations/iceberg.md
+++ b/i18n/zh/docusaurus-plugin-content-docs/current/engines/table-engines/integrations/iceberg.md
@@ -37,6 +37,7 @@ CREATE TABLE iceberg_table_local
ENGINE = IcebergLocal(path_to_table, [,format] [,compression_method])
```
+
## 引擎参数 \{#engine-arguments\}
参数说明与引擎 `S3`、`AzureBlobStorage`、`HDFS` 和 `File` 中参数的说明相同。\
@@ -69,12 +70,15 @@ CREATE TABLE iceberg_table ENGINE=IcebergS3(iceberg_conf, filename = 'test_table
```
+
## 别名 \{#aliases\}
表引擎 `Iceberg` 现在是 `IcebergS3` 的别名。
## 模式演进 \{#schema-evolution\}
-目前,借助 ClickHouse (CH),可以读取随着时间推移发生模式变更的 Iceberg 表。当前支持读取曾经增加或删除列、以及列顺序发生变化的表。也可以将原本要求非空的列修改为允许为 NULL 的列。此外,还支持对简单类型进行允许的类型转换,即:
+
+ClickHouse 支持读取其模式随时间演进的 Iceberg 表。当前支持读取曾经增加或删除列、以及列顺序发生变化的表。也可以将原本要求非空的列修改为允许为 NULL 的列。此外,还支持对简单类型进行允许的类型转换,即:
+
* int -> long
* float -> double
* decimal(P, S) -> decimal(P', S),其中 P' > P。
@@ -93,26 +97,29 @@ ClickHouse 支持 Iceberg 表的时间旅行功能,允许您在指定的时间
## 处理包含已删除行的表 \{#deleted-rows\}
-目前,仅支持带有 [position deletes](https://iceberg.apache.org/spec/#position-delete-files) 的 Iceberg 表。
+ClickHouse 支持读取使用以下删除方法的 Iceberg 表:
-以下删除方式**不受支持**:
+- [Position deletes](https://iceberg.apache.org/spec/#position-delete-files)
+- [Equality deletes](https://iceberg.apache.org/spec/#equality-delete-files)(自 25.8 版本起支持)
-* [Equality deletes](https://iceberg.apache.org/spec/#equality-delete-files)(等值删除)
-* [Deletion vectors](https://iceberg.apache.org/spec/#deletion-vectors)(在 v3 中引入的删除向量)
+以下删除方法**不支持**:
+
+- [Deletion vectors](https://iceberg.apache.org/spec/#deletion-vectors)(在 v3 中引入)
### 基本用法 \{#basic-usage\}
```sql
SELECT * FROM example_table ORDER BY 1
SETTINGS iceberg_timestamp_ms = 1714636800000
- ```
+```
```sql
SELECT * FROM example_table ORDER BY 1
SETTINGS iceberg_snapshot_id = 3547395809148285433
- ```
+```
+
+注意:在同一条查询语句中不能同时指定 `iceberg_timestamp_ms` 和 `iceberg_snapshot_id` 参数。
-注意:你不能在同一个查询中同时指定 `iceberg_timestamp_ms` 和 `iceberg_snapshot_id` 参数。
### 重要注意事项 \{#important-considerations\}
@@ -186,9 +193,10 @@ ClickHouse 支持 Iceberg 表的时间旅行功能,允许您在指定的时间
* 在 ts1 和 ts2:只显示原来的两列
* 在 ts3:显示全部三列,且第一行的 price 为 NULL
+
#### 场景 2:历史表结构与当前表结构的差异 \{#scenario-2\}
-在当前时刻执行的时间旅行查询,可能会显示与当前表不同的表结构:
+在当前时刻执行的时间旅行查询可能会显示与当前表不同的表结构:
```sql
-- Create a table
@@ -228,6 +236,7 @@ ClickHouse 支持 Iceberg 表的时间旅行功能,允许您在指定的时间
这是因为 `ALTER TABLE` 不会创建新的快照;对于当前表,Spark 会从最新的元数据文件中读取 `schema_id` 的值,而不是从快照中读取。
+
#### 场景 3:历史与当前表结构差异 \{#scenario-3\}
第二点是在进行时间旅行时,你无法获取表在尚未写入任何数据之前的状态:
@@ -249,6 +258,7 @@ ClickHouse 支持 Iceberg 表的时间旅行功能,允许您在指定的时间
在 ClickHouse 中,其行为与 Spark 保持一致。你可以在概念上将 Spark 的 Select 查询替换为 ClickHouse 的 Select 查询,它们的工作方式是相同的。
+
## 元数据文件解析 \{#metadata-file-resolution\}
在 ClickHouse 中使用 `Iceberg` 表引擎时,系统需要定位描述 Iceberg 表结构的正确 metadata.json 文件。下面是该解析过程的具体流程:
@@ -283,7 +293,7 @@ ClickHouse 支持 Iceberg 表的时间旅行功能,允许您在指定的时间
**注意**:上述所有设置都是引擎级别设置,必须在创建表时进行指定,如下所示:
-```sql
+```sql
CREATE TABLE example_table ENGINE = Iceberg(
's3://bucket/path/to/iceberg_table'
) SETTINGS iceberg_metadata_table_uuid = '6f6f6407-c6a5-465f-a808-ea8900e35a38';
@@ -291,6 +301,7 @@ CREATE TABLE example_table ENGINE = Iceberg(
**注意**:虽然 Iceberg Catalog 通常负责元数据解析,但 ClickHouse 中的 `Iceberg` 表引擎会直接将存储在 S3 中的文件解析为 Iceberg 表,这也是为什么理解这些解析规则很重要。
+
## 数据缓存 \{#data-cache\}
`Iceberg` 表引擎和表函数支持与 `S3`、`AzureBlobStorage`、`HDFS` 存储类似的数据缓存功能。请参阅[此处](../../../engines/table-engines/integrations/s3.md#data-cache)。
@@ -301,4 +312,4 @@ CREATE TABLE example_table ENGINE = Iceberg(
## 另请参阅 \{#see-also\}
-- [iceberg 表函数](/sql-reference/table-functions/iceberg.md)
+- [iceberg 表函数](/sql-reference/table-functions/iceberg.md)
\ No newline at end of file
diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/engines/table-engines/integrations/mysql.md b/i18n/zh/docusaurus-plugin-content-docs/current/engines/table-engines/integrations/mysql.md
index d90ef342a6e..b6f41148da8 100644
--- a/i18n/zh/docusaurus-plugin-content-docs/current/engines/table-engines/integrations/mysql.md
+++ b/i18n/zh/docusaurus-plugin-content-docs/current/engines/table-engines/integrations/mysql.md
@@ -62,6 +62,7 @@ SETTINGS
CREATE TABLE test_replicas (id UInt32, name String, age UInt32, money UInt32) ENGINE = MySQL(`mysql{2|3|4}:3306`, 'clickhouse', 'test_replicas', 'root', 'clickhouse');
```
+
## 使用示例 \{#usage-example\}
在 MySQL 中创建表:
@@ -87,7 +88,7 @@ mysql> select * from test;
1 row in set (0,00 sec)
```
-使用常规参数在 ClickHouse 中创建表:
+使用普通参数在 ClickHouse 中创建表:
```sql
CREATE TABLE mysql_table
@@ -127,6 +128,7 @@ SELECT * FROM mysql_table
└────────────────┴────────┘
```
+
## 设置 \{#mysql-settings\}
默认设置的效率不高,因为它们甚至不会复用连接。可以通过这些设置来提升服务器每秒可执行的查询数量。
@@ -196,4 +198,4 @@ SELECT * FROM mysql_table
## 另请参阅 \{#see-also\}
- [MySQL 表函数](../../../sql-reference/table-functions/mysql.md)
-- [将 MySQL 用作字典源](/sql-reference/dictionaries#mysql)
+- [将 MySQL 用作字典源](/sql-reference/statements/create/dictionary/sources#mysql)
\ No newline at end of file
diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/engines/table-engines/integrations/odbc.md b/i18n/zh/docusaurus-plugin-content-docs/current/engines/table-engines/integrations/odbc.md
index 2e7e6848b84..7d6acef7c75 100644
--- a/i18n/zh/docusaurus-plugin-content-docs/current/engines/table-engines/integrations/odbc.md
+++ b/i18n/zh/docusaurus-plugin-content-docs/current/engines/table-engines/integrations/odbc.md
@@ -141,5 +141,5 @@ SELECT * FROM odbc_t
## 另请参阅 \{#see-also\}
-- [ODBC 字典](/sql-reference/dictionaries#mysql)
+- [ODBC 字典](/sql-reference/statements/create/dictionary/sources#mysql)
- [ODBC 表函数](../../../sql-reference/table-functions/odbc.md)
\ No newline at end of file
diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/engines/table-engines/integrations/postgresql.md b/i18n/zh/docusaurus-plugin-content-docs/current/engines/table-engines/integrations/postgresql.md
index 4624150f4eb..b1cd517a0dd 100644
--- a/i18n/zh/docusaurus-plugin-content-docs/current/engines/table-engines/integrations/postgresql.md
+++ b/i18n/zh/docusaurus-plugin-content-docs/current/engines/table-engines/integrations/postgresql.md
@@ -229,7 +229,7 @@ CREATE TABLE pg_table_schema_with_dots (a UInt32)
**另请参阅**
* [`postgresql` 表函数](../../../sql-reference/table-functions/postgresql.md)
-* [将 PostgreSQL 用作字典源](/sql-reference/dictionaries#mysql)
+* [将 PostgreSQL 用作字典源](/sql-reference/statements/create/dictionary/sources#mysql)
## 相关内容 \{#related-content\}
diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/engines/table-engines/mergetree-family/mergetree.md b/i18n/zh/docusaurus-plugin-content-docs/current/engines/table-engines/mergetree-family/mergetree.md
index b9bc3d2cbb3..07a7b99e911 100644
--- a/i18n/zh/docusaurus-plugin-content-docs/current/engines/table-engines/mergetree-family/mergetree.md
+++ b/i18n/zh/docusaurus-plugin-content-docs/current/engines/table-engines/mergetree-family/mergetree.md
@@ -283,6 +283,56 @@ SELECT count() FROM table WHERE CounterID = 34 OR URL LIKE '%upyachka%'
按月分区的分区键可以使查询仅读取包含目标日期范围的数据块。在这种情况下,一个数据块可能包含多个日期的数据(最多可覆盖整个月)。在一个数据块内,数据按主键排序,而主键的首列不一定是日期。正因为如此,如果查询中只包含日期条件而未指定主键前缀,就会为获取某个单一日期而读取比实际需要更多的数据。
+### 在主键中对确定性表达式使用索引 \{#use-of-index-for-deterministic-expressions-in-primary-keys\}
+
+主键中不仅可以包含列名,还可以包含表达式。此类表达式不限于简单的函数链:只要是确定性的,它们可以是任意表达式树(例如嵌套函数和复合表达式)。
+
+如果一个表达式对于相同的输入值总是返回相同的结果,则该表达式是**确定性的(deterministic)**(例如:`length()`, `toDate()`, `lower()`, `left()`, `cityHash64()`, `toUUID()`;不同于 `now()` 或 `rand()`)。如果主键包含确定性表达式,ClickHouse 可以将这些表达式应用于查询中的常量值,并使用结果在主键索引上构建条件。这样就可以对 `=`, `IN` 和 `has` 等谓词跳过扫描部分数据。
+
+一个常见的用例是使主键保持紧凑(例如存储哈希值而不是很长的 `String`),同时仍然允许对原始列上的谓词使用索引。
+
+确定性(但非单射)的主键示例:
+
+```sql
+ENGINE = MergeTree()
+ORDER BY length(user_id)
+```
+
+可以利用索引的示例谓词:
+
+```sql
+SELECT * FROM table WHERE user_id = 'alice';
+SELECT * FROM table WHERE user_id IN ('alice', 'bob');
+SELECT * FROM table WHERE has(['alice', 'bob'], user_id);
+```
+
+在这些情况下,ClickHouse 会先计算一次 `length('alice')`(以及其他常量),然后使用这些长度值来收窄主键索引中的范围。由于字符串的长度**不是单射的(not injective)**,不同的 `user_id` 字符串可能具有相同的长度,因此索引可能会多读取一些 granule(误报)。查询结果仍然是正确的,因为在读取之后,仍然会应用原始谓词(`user_id = ...`、`IN` 等)。
+
+如果这个确定性表达式同时也是**单射的(injective)**(对于所使用的参数类型,不同输入不可能产生相同输出),那么 ClickHouse 还可以高效地将索引用于其否定形式:`!=`、`NOT IN` 和 `NOT has(...)`。例如,`reverse(p)` 和 `hex(p)` 对于 `String` 是单射的。
+
+一个单射主键的示例:
+
+```sql
+ENGINE = MergeTree()
+ORDER BY hex(p)
+```
+
+也支持更复杂的单射表达式,例如:
+
+```sql
+ENGINE = MergeTree()
+ORDER BY reverse(tuple(reverse(p), hex(p)))
+```
+
+可以利用索引的谓词示例:
+
+```sql
+SELECT * FROM table WHERE p != 'abc';
+SELECT * FROM table WHERE p NOT IN ('abc', '12345');
+SELECT * FROM table WHERE NOT has(['abc', '12345'], p);
+```
+
+
### 对部分单调主键使用索引 \{#use-of-index-for-partially-monotonic-primary-keys\}
以一个例子说明:考虑一个月中的日期。在一个月的范围内,它们构成一个[单调序列](https://en.wikipedia.org/wiki/Monotonic_function),但在更长时间范围内就不是单调的了。这就是一个部分单调序列。如果用户使用部分单调的主键创建表,ClickHouse 仍会照常创建稀疏索引。当用户从这类表中查询数据时,ClickHouse 会分析查询条件。如果用户希望获取索引中两个标记之间的数据,并且这两个索引标记都落在同一个月内,那么在这种特定情况下 ClickHouse 可以使用索引,因为它可以计算查询参数与索引标记之间的距离。
diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/engines/table-engines/mergetree-family/textindexes.md b/i18n/zh/docusaurus-plugin-content-docs/current/engines/table-engines/mergetree-family/textindexes.md
index 22f32691e19..e4c60befab5 100644
--- a/i18n/zh/docusaurus-plugin-content-docs/current/engines/table-engines/mergetree-family/textindexes.md
+++ b/i18n/zh/docusaurus-plugin-content-docs/current/engines/table-engines/mergetree-family/textindexes.md
@@ -7,13 +7,8 @@ title: '使用文本索引的全文搜索'
doc_type: 'reference'
---
-import BetaBadge from '@theme/badges/BetaBadge';
-
-
# 使用文本索引进行全文搜索 \{#full-text-search-with-text-indexes\}
-
-
文本索引(也称为[倒排索引](https://en.wikipedia.org/wiki/Inverted_index))可以对文本数据进行快速全文搜索。
文本索引存储从词元到包含该词元的行号的映射关系。
词元由称为分词(tokenization)的过程生成。
@@ -81,13 +76,7 @@ If query
SELECT value FROM system.settings WHERE name = 'compatibility';
```
-返回值
-
-```text
-25.4
-```
-
-或者如果设置为任何小于 26.2 的值,则需要再配置三个额外的设置才能使用文本索引:
+如果返回值小于 `26.2`(例如 `25.4`),则需要额外配置三个设置项才能使用文本索引:
```sql
SET enable_full_text_index = true;
@@ -125,7 +114,7 @@ ENGINE = MergeTree
ORDER BY key
```
-或者,可以为现有表添加一个文本索引:
+或者,要为现有表添加一个文本索引:
```sql
ALTER TABLE table
@@ -147,7 +136,7 @@ ALTER TABLE table
```
-如果你向已有表添加一个索引,我们建议为该表中已有的分区片段物化该索引(否则,在这些尚未建立索引的分区片段上进行搜索时,将会退回到较慢的穷举扫描)。
+如果你向已有表添加一个索引,我们建议为表中现有的分区片段物化此索引(否则,在这些尚未建立索引的分区片段上进行搜索时,将会回退到较慢的穷举扫描方式)。
```sql
ALTER TABLE table MATERIALIZE INDEX text_idx SETTINGS mutations_sync = 2;
diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/engines/table-engines/special/dictionary.md b/i18n/zh/docusaurus-plugin-content-docs/current/engines/table-engines/special/dictionary.md
index 26e48cb099d..82dee8fb1ae 100644
--- a/i18n/zh/docusaurus-plugin-content-docs/current/engines/table-engines/special/dictionary.md
+++ b/i18n/zh/docusaurus-plugin-content-docs/current/engines/table-engines/special/dictionary.md
@@ -9,7 +9,7 @@ doc_type: 'reference'
# Dictionary 表引擎 \{#dictionary-table-engine\}
-`Dictionary` 引擎将 [dictionary](../../../sql-reference/dictionaries/index.md) 数据显示为 ClickHouse 表。
+`Dictionary` 引擎将 [dictionary](../../../sql-reference/statements/create/dictionary/index.md) 数据显示为 ClickHouse 表。
## 示例 \{#example\}
diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/getting-started/example-datasets/cell-towers.md b/i18n/zh/docusaurus-plugin-content-docs/current/getting-started/example-datasets/cell-towers.md
index 7c4fcb32e79..1fd01b2f96f 100644
--- a/i18n/zh/docusaurus-plugin-content-docs/current/getting-started/example-datasets/cell-towers.md
+++ b/i18n/zh/docusaurus-plugin-content-docs/current/getting-started/example-datasets/cell-towers.md
@@ -168,7 +168,8 @@ SELECT mcc, count() FROM cell_towers GROUP BY mcc ORDER BY count() DESC LIMIT 10
根据上述查询以及 [MCC 列表](https://en.wikipedia.org/wiki/Mobile_country_code),基站数量最多的国家包括:美国、德国和俄罗斯。
-您可以考虑在 ClickHouse 中创建一个 [Dictionary](../../sql-reference/dictionaries/index.md) 来对这些值进行解码。
+您可以考虑在 ClickHouse 中创建一个 [Dictionary](../../sql-reference/statements/create/dictionary/index.md) 来对这些值进行解码。
+
## 使用场景:集成地理数据 \{#use-case\}
diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/integrations/data-ingestion/etl-tools/dbt/index.md b/i18n/zh/docusaurus-plugin-content-docs/current/integrations/data-ingestion/etl-tools/dbt/index.md
index ea1767f63f3..79a6b593c5c 100644
--- a/i18n/zh/docusaurus-plugin-content-docs/current/integrations/data-ingestion/etl-tools/dbt/index.md
+++ b/i18n/zh/docusaurus-plugin-content-docs/current/integrations/data-ingestion/etl-tools/dbt/index.md
@@ -30,12 +30,12 @@ dbt 可以通过一个由 ClickHouse 官方支持的适配器与 ClickHouse 集
{/*AUTOGENERATED_START*/ }
-| Page | Description |
-| ---------------------------------------------------------------------------- | ---------------------------------------------- |
-| [Features and Configurations](/integrations/dbt/features-and-configurations) | 可用功能与通用配置概述 |
-| [Materializations](/integrations/dbt/materializations) | 可用的 materialization 类型及其配置 |
-| [Guides](/integrations/dbt/guides) | 将 dbt 与 ClickHouse 结合使用的指南 |
-| [Materialized Views](/integrations/dbt/materialization-materialized-view) | 关于 materialized_view materialization 的专门文档 |
+| Page | Description |
+| --------------------------------------------------------------------------------------------- | ---------------------------------------------- |
+| [Features and Configurations](/integrations/dbt/features-and-configurations) | 可用功能与通用配置概述 |
+| [Materializations](/integrations/dbt/materializations) | 可用的 materialization 类型及其配置 |
+| [Guides](/integrations/dbt/guides) | 将 dbt 与 ClickHouse 结合使用的指南 |
+| [Materialization: materialized_view](/integrations/dbt/materialization-materialized-view) | 关于 materialized_view materialization 的专门文档 |
{/*AUTOGENERATED_END*/ }
diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/integrations/data-ingestion/etl-tools/dbt/materialization-materialized-view.md b/i18n/zh/docusaurus-plugin-content-docs/current/integrations/data-ingestion/etl-tools/dbt/materialization-materialized-view.md
index 004075584d2..15f44472ad9 100644
--- a/i18n/zh/docusaurus-plugin-content-docs/current/integrations/data-ingestion/etl-tools/dbt/materialization-materialized-view.md
+++ b/i18n/zh/docusaurus-plugin-content-docs/current/integrations/data-ingestion/etl-tools/dbt/materialization-materialized-view.md
@@ -3,8 +3,8 @@ sidebar_label: '物化: materialized_view'
slug: /integrations/dbt/materialization-materialized-view
sidebar_position: 4
description: '关于 materialized_view 物化方式的专用文档'
-keywords: ['ClickHouse', 'dbt', 'materialized view', '可刷新', '外部目标表', '补齐']
-title: 'Materialized Views'
+keywords: ['ClickHouse', 'dbt', 'materialized_view', '可刷新', 'Materialized Views', '补齐']
+title: '物化: materialized_view'
doc_type: 'guide'
---
@@ -292,13 +292,62 @@ GROUP BY event_date, event_type
1. 更新 `materialization_target_table()` 调用
2. 运行 `dbt run --full-refresh -s your_mv_model`
-### 隐式目标与显式目标方法的行为对比\{#explicit-target-behavior\}
+### 常见问题排查 \{#explicit-target-troubleshooting\}
-| Operation | 隐式目标 | 显式目标 |
-| --- | --- | --- |
-| First dbt run | 创建所有资源 | 创建所有资源 |
-| Next dbt run | **无法单独管理资源,所有操作将一并执行:** **target table**: 通过 `on_schema_change` 设置来管理变更。默认为 `ignore`,因此新列不会被处理。 **MVs**:全部通过 `alter table modify query` 操作进行更新 | **可以按资源单独应用变更: target table**: 自动检测它们是否为由 dbt 定义的 MVs 对应的 target tables。若是,则列结构的演进默认由 `mv_on_schema_change` 设置(值为 `fail`)来管理,因此如果列发生变化将会失败。我们将此默认值设置为一层保护机制。 **MVs**:其 SQL 会通过 `alter table modify query` 操作进行更新。 |
-| dbt run --full-refresh | **无法单独管理资源,所有操作将一并执行: target table**: target table 会被重新创建为空表。可通过 `catchup` 配置,使用所有 MVs 的 SQL 一起进行回填。`catchup` 默认为 `True`。 **MVs**:全部被重新创建。 | **变更将按资源单独应用: target table:**将按常规方式重新创建。 **MVs**:先 drop 再重新创建。`catchup` 可用于初始回填。`catchup` 默认为 `True`。 **注意:在此过程中,在 MVs 重新创建之前,target table 将为空或仅部分加载。为避免这种情况,请查看下一节关于如何迭代 target table 的内容。**|
+#### 在执行 `run` 期间或之后目标表为空 \{#target-table-empty\}
+
+出现这种情况可能有以下几种原因:
+
+- materialized view 可能被配置为 `catchup=False`,或者目标表被配置为 `repopulate_from_mvs_on_full_refresh=False`,因此在创建 materialized view 或重建目标表时不会执行回填。这是预期行为,因此如果希望使用 materialized view 的 SQL 重新插入数据,请确保在 materialized view 中设置 `catchup=True`(默认值),或者在目标表中设置 `repopulate_from_mvs_on_full_refresh=True`。注意不要同时启用这两个设置,以避免产生重复数据。更多详情请查看[配置部分](#explicit-target-configuration)。
+- 当执行 `dbt run --full-refresh` 时,如果 materialized view 使用默认的 `catchup=True`,目标表会被重建,这些 materialized view 会依次重新插入数据。为避免这种情况,请查看[对显式目标执行 Full refresh](#explicit-target-full-refresh)。
+
+#### 在目标表中执行 `dbt run --full-refresh` 且设置 `repopulate_from_mvs_on_full_refresh=True` 时,会使用旧版本 materialized view 的逻辑,而不是项目中当前的 SQL 定义 \{#full-refresh-with-repopulate-from-mvs-on-full-refresh\}
+
+`repopulate_from_mvs_on_full_refresh=True` 会使用 ClickHouse 中已存在的 materialized view SQL 定义。要确保使用新的 materialized view 定义,请先对每个 materialized view 执行一次 `dbt run`,然后再对目标表执行 `dbt run --full-refresh`。
+
+#### 在执行一次 run 之后出现重复数据 \{#duplicate-data\}
+
+可能原因:
+
+- materialized view 上设置了 `catchup=True`,并且目标表上设置了 `repopulate_from_mvs_on_full_refresh=True`:根据你希望执行的操作,仅保留其中一个。有关更多细节,请查看[配置章节](#explicit-target-configuration)。
+- 目标表未使用 `WHERE 0` 定义:目标表应在创建时为空,但如果未包含 `WHERE 0`,内部查询可能会插入数据。请确保包含该子句。
+
+#### 在执行 `dbt run --full-refresh` 后进行活跃摄取时的数据丢失 \{#data-loss-active-ingestion\}
+
+在执行 `dbt run --full-refresh` 之后,源表中的部分行在目标表中缺失。
+ClickHouse materialized view 的作用类似于 insert 触发器——它们只会在自身存在期间捕获数据。在完整刷新过程中,会有一个短暂的时间窗口,MV 会被删除并重新创建(“盲窗口”)。在此窗口期间插入到源表中的任何行都不会被捕获。有关更多详情,请参见[活跃摄取期间的行为](#behavior-during-active-ingestion)一节。
+
+### 调试方法 \{#debugging-techniques\}
+
+#### 检查 ClickHouse 中当前 MV 的写入目标 \{#check-mv-target\}
+
+查询 `system.tables`,以查看 materialized view 当前写入到哪里:
+
+```sql
+SELECT
+ name as mv_name,
+ replaceRegexpOne(
+ create_table_query,
+ '.*TO\\s+`?([^`\\s(]+)`?\\.`?([^`\\s(]+)`?.*',
+ '\\1.\\2'
+ ) AS target_table
+FROM system.tables
+WHERE database = 'your_schema'
+ AND engine = 'MaterializedView'
+```
+
+
+#### 检查 dbt 是否将某个表识别为 materialized view 目标 \{#check-dbt-recognition\}
+
+在执行 dbt run 时,留意如下日志条目:
+
+>Table `` is used as a target by a dbt-managed materialized view. Defaulting mv_on_schema_change to "fail" to prevent data loss.
+
+如果出现这条消息,说明 dbt 已检测到该表被至少一个由 dbt 管理的 materialized view 作为目标使用。如果你预期会看到这条消息但实际没有,请确认以下事项:
+
+- materialized view 模型是否正确地定义了 `{{ materialization_target_table(ref('your_target')) }}`
+- materialized view 模型在其配置中是否包含 `materialized='materialized_view'`
+- materialized view 和其目标表是否都已经至少运行过一次
### 从隐式目标迁移到显式目标 \{#migration-implicit-to-explicit\}
@@ -367,23 +416,34 @@ select a, b, c from {{ source('raw', 'table_2') }}
**3. 按需根据[显式目标](#explicit-target)部分中的说明进行迭代。**
-## 活跃摄取期间的行为 \{#behavior-during-active-ingestion\}
+## 隐式目标与显式目标方法的行为对比\{#behavior-comparison\}
+
+### 它们的一般行为方式 \{#general-behavior\}
+
+| Operation | 隐式 target | 显式 target |
+| --- | --- | --- |
+| First dbt run | 创建所有资源 | 创建所有资源 |
+| Next dbt run | **资源无法单独管理,所有变更一次性执行:** **target table**: 使用 `on_schema_change` 设置来管理变更。默认值为 `ignore`,因此新列不会被处理。 **Materialized views**:全部通过 `alter table modify query` 操作进行更新 | **变更可以单独应用: target table**: 自动检测其是否为由 dbt 定义的 materialized views 的 target table。如果是,则列演进默认通过 `mv_on_schema_change` 设置为 `fail` 来管理,因此在列发生变更时会报错。我们将此默认值作为一层保护机制。 **Materialized views**:其 SQL 会通过 `alter table modify query` 操作进行更新。 |
+| dbt run --full-refresh | **资源无法单独管理,所有变更一次性执行: target table**: target table 会被重新创建为空表。可以通过 `catchup` 配置,使用所有 materialized views 的 SQL 一次性进行回填。`catchup` 的默认值为 `True`。 **Materialized views**:全部会被重新创建。 | **变更将被单独应用: target table:** 将按常规方式被重新创建。 **Materialized views**:先 drop 再重新创建。`catchup` 可用于初始回填。`catchup` 的默认值为 `True`。 **注意:在此过程中,在 materialized views 重新创建完成之前,target table 将为空或仅部分加载。为避免这种情况,请查看下一节关于如何迭代 target table 的内容。**|
+
+### 活跃摄取期间的行为 \{#behavior-during-active-ingestion\}
-由于 ClickHouse 的 materialized view 充当**插入触发器(insert trigger)**,它们只会在自身存在期间捕获数据。如果在某个时间窗口内(例如在执行 `--full-refresh` 期间)一个 materialized view 被删除并重新创建,那么在该窗口中插入到源表的任何行都**不会**被该 MV 处理。这种情况被称为 MV 处于“盲区”(blind)状态。
+在迭代你的模型时,需要了解不同操作如何与正在插入的数据交互:
-另外,**追赶(catch-up)**过程(无论是通过 MV 的 `catchup`,还是通过目标表的 `repopulate_from_mvs_on_full_refresh`)都会使用 MV 的 SQL 运行一条 `INSERT INTO ... SELECT`。如果此时源表上也在发生插入操作,则追赶查询可能会包含那些 MV 已经处理过的行(或将在 MV 创建后立即处理的行),从而可能在目标表中造成**重复数据**。在目标表上使用例如 `ReplacingMergeTree` 这样的去重引擎可以降低此风险。
+- 由于 ClickHouse 的 materialized view 充当**插入触发器(insert trigger)**,它们只会在自身存在期间捕获数据。如果在某个时间窗口内(例如在执行 `--full-refresh` 期间)一个 materialized view 被删除并重新创建,那么在该窗口中插入到源表的任何行都**不会**被该 materialized view 处理。这种情况被称为该 materialized view 处于“盲区”(blind)状态。
+- 各种不同的 `catchup` 过程都基于使用 materialized view 的 SQL 执行的 `INSERT INTO ... SELECT` 操作,并且独立于 materialized view 的工作方式。一旦 `INSERT` 开始执行,新的数据将不会被该 `INSERT` 捕获,但会被已附加的 materialized view 捕获。
下表总结了在源表上存在持续插入时,各类操作的安全性。
-### 隐式目标操作 \{#ingestion-implicit-target\}
+#### 隐式目标操作 \{#ingestion-implicit-target\}
| Operation | Internal process | Safety while inserts are happening |
|-----------|------------------|------------------------------------|
-| First `dbt run` | 1. 创建目标表 2. 插入数据(如果 `catchup=True`) 3. 创建物化视图(MV) | ⚠️ **在步骤 1 到 3 之间,MV 处于“盲区”。** 在此时间窗口内插入到源表的任何行都不会被捕获。 |
-| Subsequent `dbt run` | `ALTER TABLE ... MODIFY QUERY` | ✅ 安全。MV 会以原子方式更新。 |
-| `dbt run --full-refresh` | 1. 创建备份表 2. 插入数据(如果 `catchup=True`) 3. 删除 MV 4. 交换表 5. 重新创建 MV | ⚠️ **在重新创建期间,MV 处于“盲区”。** 在步骤 3 到 5 之间插入到源表的数据不会出现在新的目标表中。 |
+| First `dbt run` | 1. 创建目标表 2. 插入数据(如果 `catchup=True`) 3. 创建 materialized view | ⚠️ **在步骤 1 到 3 之间,materialized view 处于“盲区”。** 在此时间窗口内插入到源表的任何行都不会被捕获。 |
+| Subsequent `dbt run` | `ALTER TABLE ... MODIFY QUERY` | ✅ 安全。materialized view 会以原子方式更新。 |
+| `dbt run --full-refresh` | 1. 创建备份表 2. 插入数据(如果 `catchup=True`) 3. 删除 materialized view 4. 交换表 5. 重新创建 materialized view | ⚠️ **在重新创建期间,materialized view 处于“盲区”。** 在步骤 3 到 5 之间插入到源表的数据不会出现在新的目标表中。 |
-### 显式目标操作 \{#ingestion-explicit-target\}
+#### 显式目标操作 \{#ingestion-explicit-target\}
**materialized view 模型:**
diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/integrations/data-sources/cassandra.md b/i18n/zh/docusaurus-plugin-content-docs/current/integrations/data-sources/cassandra.md
index 2f74688dac2..c8c83e71b85 100644
--- a/i18n/zh/docusaurus-plugin-content-docs/current/integrations/data-sources/cassandra.md
+++ b/i18n/zh/docusaurus-plugin-content-docs/current/integrations/data-sources/cassandra.md
@@ -9,4 +9,4 @@ doc_type: 'reference'
# Cassandra 集成 \{#cassandra-integration\}
-可以通过字典与 Cassandra 集成。更多详情请参阅[此处](/sql-reference/dictionaries#cassandra)。
\ No newline at end of file
+可以通过字典与 Cassandra 集成。更多详情请参阅[此处](/sql-reference/statements/create/dictionary/sources/cassandra)。
\ No newline at end of file
diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/integrations/language-clients/csharp.md b/i18n/zh/docusaurus-plugin-content-docs/current/integrations/language-clients/csharp.md
index ff93e415588..b5ba8f6c728 100644
--- a/i18n/zh/docusaurus-plugin-content-docs/current/integrations/language-clients/csharp.md
+++ b/i18n/zh/docusaurus-plugin-content-docs/current/integrations/language-clients/csharp.md
@@ -42,9 +42,6 @@ import connection_details_csharp from '@site/static/images/_snippets/connection-
`ClickHouse.Driver` 支持以下 .NET 版本:
-* .NET Framework 4.6.2
-* .NET Framework 4.8
-* .NET Standard 2.1
* .NET 6.0
* .NET 8.0
* .NET 9.0
@@ -355,8 +352,8 @@ using ClickHouse.Driver;
using ClickHouse.Driver.ADO.Parameters;
var parameters = new ClickHouseParameterCollection();
-parameters.Add("id", 1L);
-parameters.Add("name", "Alice");
+parameters.AddParameter("id", 1L);
+parameters.AddParameter("name", "Alice");
await client.ExecuteNonQueryAsync(
"INSERT INTO default.my_table (id, name) VALUES ({id:Int64}, {name:String})",
@@ -413,7 +410,7 @@ var options = new InsertOptions
using ClickHouse.Driver.ADO.Parameters;
var parameters = new ClickHouseParameterCollection();
-parameters.Add("max_id", 100L);
+parameters.AddParameter("max_id", 100L);
var reader = await client.ExecuteReaderAsync(
"SELECT * FROM default.my_table WHERE id < {max_id:Int64}",
@@ -683,7 +680,7 @@ while (reader.Read())
3. **在 SQL 类型提示中指定时区。** 当向非 UTC 的列传递带有 `Unspecified` DateTime 值的参数时,在 SQL 中包含时区信息:
```csharp
var parameters = new ClickHouseParameterCollection();
- parameters.Add("dt", myDateTime);
+ parameters.AddParameter("dt", myDateTime);
await client.ExecuteNonQueryAsync(
"INSERT INTO table (dt) VALUES ({dt:DateTime('Europe/Amsterdam')})",
diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/integrations/language-clients/java/client/client.mdx b/i18n/zh/docusaurus-plugin-content-docs/current/integrations/language-clients/java/client/client.mdx
index 41cc5cf0e09..5591deaf564 100644
--- a/i18n/zh/docusaurus-plugin-content-docs/current/integrations/language-clients/java/client/client.mdx
+++ b/i18n/zh/docusaurus-plugin-content-docs/current/integrations/language-clients/java/client/client.mdx
@@ -34,8 +34,8 @@ import WideTableWrapper from '@site/src/components/WideTableWrapper/WideTableWra
## 设置 \{#setup\}
* Maven Central(项目页面):https://mvnrepository.com/artifact/com.clickhouse/client-v2
- * 每夜构建版本(仓库链接):https://central.sonatype.com/repository/maven-snapshots/
- * 旧版 Nightly 构建仓库(仓库链接):https://s01.oss.sonatype.org/content/repositories/snapshots/
+ * Nightly 构建版本(仓库链接):https://central.sonatype.com/repository/maven-snapshots/
+ * 旧版每夜构建仓库(仓库链接):https://s01.oss.sonatype.org/content/repositories/snapshots/
@@ -107,7 +107,7 @@ import WideTableWrapper from '@site/src/components/WideTableWrapper/WideTableWra
.build();
```
- 通过 SSL 客户端证书进行身份验证需要设置用户名、启用 SSL 身份验证、设置客户端证书和客户端密钥,方法是分别调用 `setUsername(String)`、`useSSLAuthentication(boolean)`、`setClientCertificate(String)` 和 `setClientKey(String)`:
+ 通过 SSL 客户端证书进行身份验证需要设置用户名、启用 SSL 身份验证、设置客户端证书和客户端密钥,方法是分别调用 `setUsername(String)`、`useSSLAuthentication(boolean)`、`setClientCertificate(String)` 和 `setClientKey(String)`:
```java showLineNumbers
Client client = new Client.Builder()
@@ -122,10 +122,10 @@ import WideTableWrapper from '@site/src/components/WideTableWrapper/WideTableWra
请使用诸如 [openssl](https://docs.openssl.org/master/man1/openssl/) 之类的工具来验证证书和密钥:
- * 检查私钥完整性:`openssl rsa -in [key-file.key] -check -noout`
- * 检查客户端证书中的 CN 是否与相应的 USER 匹配:
+ * 检查密钥完整性:`openssl rsa -in [key-file.key] -check -noout`
+ * 检查客户端证书中的 CN 是否与对应的 USER 一致:
* 从用户证书中获取 CN - `openssl x509 -noout -subject -in [user.cert]`
- * 确认数据库中已设置相同的值:`select name, auth_type, auth_params from system.users where auth_type = 'ssl_certificate'`(查询会输出 `auth_params` 字段,其内容类似 ` {"common_names":["some_user"]}`)
+ * 确认在数据库中已设置相同的值:`select name, auth_type, auth_params from system.users where auth_type = 'ssl_certificate'`(查询结果中的 `auth_params` 字段内容类似于 ` {"common_names":["some_user"]}`)
:::
@@ -155,9 +155,9 @@ import WideTableWrapper from '@site/src/components/WideTableWrapper/WideTableWra
| Method | Arguments | Description | Default | Key |
| ---------------------------------------------------- | ------------------------------------- | --------------------------------------------- | --------- | --------------------- |
- | `setUsername(String username)` | `username` - 用于认证的用户名 | 为将通过后续配置选择的认证方式设置用户名 | `default` | `user` |
- | `setPassword(String password)` | `password` - 机密值 | 为密码认证设置机密值,并实际选择密码认证作为认证方式 | - | `password` |
- | `setAccessToken(String accessToken)` | `accessToken` - 访问令牌字符串 | 设置访问令牌,以通过相应的认证方式进行身份验证 | - | `access_token` |
+ | `setUsername(String username)` | `username` - 用于身份验证的用户名 | 为将在后续配置中选定的身份验证方式设置用户名 | `default` | `user` |
+ | `setPassword(String password)` | `password` - 机密值 | 为密码认证设置机密值,并实际将密码认证设为所使用的身份验证方式 | - | `password` |
+ | `setAccessToken(String accessToken)` | `accessToken` - 访问令牌字符串 | 设置访问令牌,以通过对应的认证方式进行身份验证 | - | `access_token` |
| `useSSLAuthentication(boolean useSSLAuthentication)` | `useSSLAuthentication` - 启用 SSL 认证的标志 | 将 SSL 客户端证书设置为一种认证方式。 | - | `ssl_authentication` |
| `useHTTPBasicAuth(boolean useBasicAuth)` | `useBasicAuth` - 启用/禁用的标志 | 设置在用户密码认证中是否应使用基本 HTTP 认证。可解决包含特殊字符的密码所导致的问题。 | `true` | `http_use_basic_auth` |
| `useBearerTokenAuth(String bearerToken)` | `bearerToken` - 编码后的 Bearer 令牌 | 指定是否使用 Bearer 认证以及要使用的令牌。令牌将按原样发送。 | - | `bearer_token` |
@@ -175,13 +175,13 @@ import WideTableWrapper from '@site/src/components/WideTableWrapper/WideTableWra
- | Method | Arguments | Description | Default | Key |
- | ------------------------------------ | -------------------- | ------------------------------------------------------------------- | ------- | -------------------- |
- | `setSocketRcvbuf(long size)` | `size` - 以字节为单位的大小 | 设置 TCP socket 接收缓冲区。该缓冲区位于 JVM 内存之外(堆外内存)。 | `8196` | `socket_rcvbuf` |
- | `setSocketSndbuf(long size)` | `size` - 以字节为单位的大小 | 设置 TCP socket 发送缓冲区。该缓冲区位于 JVM 内存之外(堆外内存)。 | `8196` | `socket_sndbuf` |
- | `setSocketKeepAlive(boolean value)` | `value` - 启用/禁用的标志 | 为每个 TCP socket 设置 `SO_KEEPALIVE` 选项。TCP Keep Alive 启用用于检查连接是否存活的机制。 | - | `socket_keepalive` |
- | `setSocketTcpNodelay(boolean value)` | `value` - 启用/禁用的标志 | 为每个 TCP socket 设置 `SO_NODELAY` 选项。该 TCP 选项会使 socket 尽可能立即发送数据。 | - | `socket_tcp_nodelay` |
- | `setSocketLinger(int secondsToWait)` | `secondsToWait` - 秒数 | 为客户端创建的每个 TCP socket 设置延迟关闭时间(linger time)。 | - | `socket_linger` |
+ | Method | Arguments | Description | Default | Key |
+ | ------------------------------------ | -------------------- | -------------------------------------------------------------------- | ------- | -------------------- |
+ | `setSocketRcvbuf(long size)` | `size` - 以字节为单位的大小 | 设置 TCP socket 接收缓冲区。该缓冲区位于 JVM 内存之外(堆外内存)。 | `8196` | `socket_rcvbuf` |
+ | `setSocketSndbuf(long size)` | `size` - 以字节为单位的大小 | 设置 TCP socket 发送缓冲区。该缓冲区位于 JVM 内存之外(堆外内存)。 | `8196` | `socket_sndbuf` |
+ | `setSocketKeepAlive(boolean value)` | `value` - 启用/禁用的标志 | 为每个 TCP socket 设置 `SO_KEEPALIVE` 选项。启用 TCP Keep-Alive 机制,用于检查连接是否存活。 | - | `socket_keepalive` |
+ | `setSocketTcpNodelay(boolean value)` | `value` - 启用/禁用的标志 | 为每个 TCP socket 设置 `SO_NODELAY` 选项。该 TCP 选项会使 socket 尽可能立即发送数据。 | - | `socket_tcp_nodelay` |
+ | `setSocketLinger(int secondsToWait)` | `secondsToWait` - 秒数 | 设置由客户端创建的每个 TCP socket 的延迟关闭时间(linger time)。 | - | `socket_linger` |
@@ -208,13 +208,13 @@ import WideTableWrapper from '@site/src/components/WideTableWrapper/WideTableWra
- | 方法 | 参数 | 描述 | 默认值 | 键 |
- | ------------------------------------------------- | -------------------------------------------------------- | -------------------- | --- | ---------------------------------------- |
- | `addProxy(ProxyType type, String host, int port)` | `type` - 代理类型 `host` - 代理主机名或 IP `port` - 代理端口 | 设置用于与服务器通信的代理。 | - | `proxy_type`, `proxy_host`, `proxy_port` |
- | `setProxyCredentials(String user, String pass)` | `user` - 代理用户名 `pass` - 密码 | 设置用于通过代理进行身份验证的用户凭据。 | - | `proxy_user`, `proxy_password` |
+ | 方法 | 参数 | 描述 | 默认值 | 键 |
+ | ------------------------------------------------- | -------------------------------------------------------- | -------------- | --- | ---------------------------------------- |
+ | `addProxy(ProxyType type, String host, int port)` | `type` - 代理类型 `host` - 代理主机名或 IP `port` - 代理端口 | 设置代理,用于与服务器通信。 | - | `proxy_type`, `proxy_host`, `proxy_port` |
+ | `setProxyCredentials(String user, String pass)` | `user` - 代理用户名 `pass` - 密码 | 设置用于代理认证的用户凭据。 | - | `proxy_user`, `proxy_password` |
-
+
| Method | Arguments | Description | Default | Key |
| ------------------------------------------- | -------------------------------------- | ------------------------------ | ------- | ------ |
| `setHttpCookiesEnabled(boolean enabled)` | `enabled` - 用于启用/禁用的标志位 | 设置是否应记住 HTTP cookie 并将其发送回服务器。 | - | - |
@@ -224,10 +224,10 @@ import WideTableWrapper from '@site/src/components/WideTableWrapper/WideTableWra
- | Method | Arguments | Description | Default | Key |
- | ----------------------------------------------- | --------------------------------- | ----------------------------------------------------------------------------------------- | ------- | ------ |
- | `serverSetting(String name, String value)` | `name` - 设置名称 `value` - 设置值 | 设置随每个查询一起发送到服务器的设置。单次操作的设置可以覆盖它。[设置列表](/operations/settings/query-level) | `none` | `none` |
- | `serverSetting(String name, Collection values)` | `name` - 设置名称 `values` - 设置值 | 设置随每个查询一起发送到服务器的、包含多个值的设置,例如 [roles](/interfaces/http#setting-role-with-query-parameters) | `none` | `none` |
+ | 方法 | 参数 | 描述 | 默认值 | 键 |
+ | ----------------------------------------------- | --------------------------------- | ----------------------------------------------------------------------------------------- | ------ | ------ |
+ | `serverSetting(String name, String value)` | `name` - 设置名称 `value` - 设置值 | 设置随每个查询一起发送到服务器的设置。单次操作的设置可以覆盖它。[设置列表](/operations/settings/query-level) | `none` | `none` |
+ | `serverSetting(String name, Collection values)` | `name` - 设置名称 `values` - 设置值 | 设置随每个查询一起发送到服务器的、包含多个值的设置,例如 [roles](/interfaces/http#setting-role-with-query-parameters) | `none` | `none` |
@@ -256,6 +256,44 @@ import WideTableWrapper from '@site/src/components/WideTableWrapper/WideTableWra
+ ### 客户端标识 \{#client-identification\}
+
+ 查询日志中有两个字段用于标识发起请求的应用程序:`client_name` 和 `http_user_agent`。原生 TCP 协议使用 `client_name` 来标识应用程序,HTTP 协议使用 `http_user_agent` 来标识应用程序。Client builder 提供了 `setClientName` 方法,可为两种协议设置正确的值。
+ `http_user_agent` 字段按照 `User-Agent` 请求头的通用格式进行设置:`application-name[/version] [(operating-system; architecture; ...)]`。
+ 该组值会在每一层(应用程序、客户端库、HTTP 客户端库)中重复出现。通过 `setClientName` 方法设置的内容在列表中排在最前面。
+
+ 例如:
+
+ ```java showLineNumbers
+ client.setClientName("my-app-01/1.0");
+ ```
+
+ 将产生以下 `http_user_agent` 值:
+
+ ```
+ my-app-01/1.0 clickhouse-java-v2/0.9.6-SNAPSHOT (Linux; jvm:17.0.17) Apache-HttpClient/5.4.4
+ ```
+
+ 应用程序可以设置自定义 HTTP 请求头 `User-Agent` 来标识自身。但 `clickhouse-java-v2/0.9.6-SNAPSHOT` 部分将被追加到该请求头的末尾。
+
+ ### 操作标识 \{#operation-identification\}
+
+ 查询日志还有另外两个字段 `query_id` 和 `log_comment`,可用于标识某个操作并向查询日志中添加附加信息。
+
+ `query_id` 是操作的唯一标识符。应用程序可通过调用 `QuerySettings` 类的 `setQueryId` 方法来设置该标识符。
+
+ ```java showLineNumbers
+ QuerySettings querySettings = new QuerySettings();
+ querySettings.setQueryId("some-query-id");
+ ```
+
+ `log_comment` 是可以添加到查询日志中的注释。应用程序可以通过调用 `QuerySettings` 类的 `logComment` 方法来设置该注释。
+
+ ```java showLineNumbers
+ QuerySettings querySettings = new QuerySettings();
+ querySettings.logComment("some-comment");
+ ```
+
### 服务器设置 \{#server-settings\}
服务器端设置可以在客户端创建时在客户端级别配置一次(参见 `Builder` 的 `serverSetting` 方法),也可以在操作级别进行配置(参见操作设置类的 `serverSetting`)。
@@ -285,7 +323,7 @@ import WideTableWrapper from '@site/src/components/WideTableWrapper/WideTableWra
### 自定义 HTTP 请求头 \{#custom-http-header\}
- 可以为所有操作(客户端级别)或单个操作(操作级别)设置自定义 HTTP 头。
+ 可以为所有操作(客户端级别)或单个操作(操作级别)设置自定义 HTTP 头。
```java showLineNumbers
@@ -295,7 +333,7 @@ import WideTableWrapper from '@site/src/components/WideTableWrapper/WideTableWra
```
- 当通过 `setOption` 方法设置选项时(无论是 `Client.Builder` 还是操作设置类),自定义请求头名称应以 `http_header_` 为前缀。此时,可以使用 `com.clickhouse.client.api.ClientConfigProperties#httpHeader()` 方法。
+ 当通过 `setOption` 方法设置选项时(无论是 `Client.Builder` 还是操作设置类),自定义请求头名称应以 `http_header_` 为前缀。此时,可以使用 `com.clickhouse.client.api.ClientConfigProperties#httpHeader()` 方法。
## 常用术语定义 \{#common-definitions\}
@@ -303,9 +341,9 @@ import WideTableWrapper from '@site/src/components/WideTableWrapper/WideTableWra
[支持的格式](/interfaces/formats) 的枚举类型,包含 ClickHouse 支持的所有格式。
- * `raw` - 需要由用户自行对原始数据进行转码
- * `full` - 客户端可自行完成数据转码,并接受原始数据流
- * `-` - 表示 ClickHouse 不支持针对该格式执行此操作
+ * `raw` - 由用户负责对原始数据进行转码
+ * `full` - 客户端可以自行对数据进行转码,并接收原始数据流
+ * `-` - ClickHouse 不支持对此格式执行该操作
此客户端版本支持:
@@ -478,15 +516,15 @@ import WideTableWrapper from '@site/src/components/WideTableWrapper/WideTableWra
**配置方法**
- | 方法 | 描述 |
- | ----------------------------------------------- | ----------------------------------------------------- |
- | `setQueryId(String queryId)` | 设置要分配给该操作的查询 ID。默认值:`null`。 |
- | `setDeduplicationToken(String token)` | 设置去重令牌。该令牌将发送到服务器,并可用于标识此查询。默认值:`null`。 |
- | `setInputStreamCopyBufferSize(int size)` | 拷贝缓冲区大小。在写入操作期间,该缓冲区用于将用户提供的输入流中的数据复制到输出流。默认值:`8196`。 |
- | `serverSetting(String name, String value)` | 为单次操作设置单个服务器端配置项。 |
- | `serverSetting(String name, Collection values)` | 为某个操作设置可包含多个值的单个服务器配置项。集合中的元素应为 `String` 值。 |
- | `setDBRoles(Collection dbRoles)` | 设置在执行操作前要启用的数据库角色。集合中的元素应为 `String` 值。 |
- | `setOption(String option, Object value)` | 以原始格式设置配置选项。这不是服务器端设置。 |
+ | 方法 | 描述 |
+ | ----------------------------------------------- | --------------------------------------------------- |
+ | `setQueryId(String queryId)` | 设置将要分配给该操作的查询 ID。默认值:`null`。 |
+ | `setDeduplicationToken(String token)` | 设置去重令牌。该令牌将发送到服务器,并可用于标识该查询。默认值:`null`。 |
+ | `setInputStreamCopyBufferSize(int size)` | 复制缓冲区大小。写入操作时,该缓冲区用于将用户提供的输入流中的数据复制到输出流。默认值:`8196`。 |
+ | `serverSetting(String name, String value)` | 为单次操作设置单个服务器端配置项。 |
+ | `serverSetting(String name, Collection values)` | 为某个操作设置可包含多个值的单个服务器配置项。集合中的元素应为 `String` 值。 |
+ | `setDBRoles(Collection dbRoles)` | 设置在执行操作前要应用的数据库角色。集合中的元素应为 `String` 值。 |
+ | `setOption(String option, Object value)` | 以原始格式设置配置选项。这不是服务器端设置。 |
### InsertResponse \{#insertresponse\}
@@ -496,10 +534,10 @@ import WideTableWrapper from '@site/src/components/WideTableWrapper/WideTableWra
应尽快关闭此对象以释放连接,因为在完全读取完前一个响应的所有数据之前,该连接无法被重用。
:::
- | 方法 | 说明 |
- | ------------------------------- | ------------------------------------------- |
- | `OperationMetrics getMetrics()` | 返回一个包含该操作各项指标的对象。 |
- | `String getQueryId()` | 返回为该操作分配的查询 ID,该 ID 由应用程序(通过操作设置)指定或由服务器生成。 |
+ | 方法 | 说明 |
+ | ------------------------------- | -------------------------------------------- |
+ | `OperationMetrics getMetrics()` | 返回一个包含该操作各项指标的对象。 |
+ | `String getQueryId()` | 返回分配给该操作的查询 ID,该 ID 由应用程序(通过操作设置)指定,或由服务器生成。 |
## 查询 API \{#query-api\}
@@ -572,7 +610,7 @@ import WideTableWrapper from '@site/src/components/WideTableWrapper/WideTableWra
**返回值**
- `QueryResponse` 类型的 Future——包含结果数据集以及诸如服务器端指标之类的附加信息。使用完数据集后应关闭 Response 对象。
+ `QueryResponse` 类型的 Future - 结果数据集及服务器端指标等附加信息。使用完数据集后应关闭 Response 对象。
**示例**
@@ -644,39 +682,39 @@ import WideTableWrapper from '@site/src/components/WideTableWrapper/WideTableWra
**配置方法**
- | 方法 | 说明 |
- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
- | `setQueryId(String queryId)` | 为该操作设置要分配的查询 ID。 |
- | `setFormat(ClickHouseFormat format)` | 设置响应格式。完整列表请参见 `RowBinaryWithNamesAndTypes`。 |
- | `setMaxExecutionTime(Integer maxExecutionTime)` | 在服务器端设置该操作的最大执行时间。不会影响读取超时设置。 |
- | `waitEndOfQuery(Boolean waitEndOfQuery)` | 请求服务器在发送响应前等待查询完成。 |
- | `setUseServerTimeZone(Boolean useServerTimeZone)` | 将使用服务器时区(参见客户端配置)来解析操作结果中的日期/时间类型。默认值为 `false`。 |
- | `setUseTimeZone(String timeZone)` | 请求服务器在时间转换时使用 `timeZone`。参见 [session_timezone](/operations/settings/settings#session_timezone)。 |
- | `serverSetting(String name, String value)` | 为单次操作设置单个服务器配置项。 |
- | `serverSetting(String name, Collection values)` | 为某个操作设置包含多个值的单个服务器配置项。集合中的元素必须是 `String` 类型的值。 |
- | `setDBRoles(Collection dbRoles)` | 设置在执行操作前要应用的数据库角色。集合中的元素应为 `String` 值。 |
- | `setOption(String option, Object value)` | 以原始格式设置配置选项。这不是服务器级设置。 |
+ | 方法 | 说明 |
+ | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+ | `setQueryId(String queryId)` | 设置要分配给该操作的查询 ID。 |
+ | `setFormat(ClickHouseFormat format)` | 设置响应数据格式。完整列表请参见 `RowBinaryWithNamesAndTypes`。 |
+ | `setMaxExecutionTime(Integer maxExecutionTime)` | 在服务器端设置该操作的最大执行时间。不会影响读取超时设置。 |
+ | `waitEndOfQuery(Boolean waitEndOfQuery)` | 请求服务器在发送响应前等待查询完成。 |
+ | `setUseServerTimeZone(Boolean useServerTimeZone)` | 服务端时区(参见客户端配置)将用于解析操作结果中的日期/时间类型。默认值为 `false`。 |
+ | `setUseTimeZone(String timeZone)` | 请求服务器在进行时间转换时使用 `timeZone`。参见 [session_timezone](/operations/settings/settings#session_timezone)。 |
+ | `serverSetting(String name, String value)` | 为单次操作设置单个服务器端设置。 |
+ | `serverSetting(String name, Collection values)` | 为某个操作设置包含多个值的单个服务器配置项。集合中的元素应为 `String` 类型的值。 |
+ | `setDBRoles(Collection dbRoles)` | 设置在执行操作前要启用的数据库角色。集合中的元素应为 `String` 值。 |
+ | `setOption(String option, Object value)` | 以原始格式设置配置选项。这不是服务器端设置。 |
### QueryResponse \{#queryresponse\}
用于保存查询执行结果的响应对象。仅当客户端从服务器收到响应时才可用。
:::note
- 应尽快关闭此对象以释放连接,因为在完全读取完上一个响应的所有数据之前,连接无法被重用。
+ 应尽快关闭此对象以释放连接,因为在完全读取完前一个响应的所有数据之前,该连接无法被重用。
:::
- | 方法 | 说明 |
- | ------------------------------- | ------------------------------------------- |
- | `ClickHouseFormat getFormat()` | 返回响应数据的编码格式。 |
- | `InputStream getInputStream()` | 返回按指定格式编码的未压缩数据字节流。 |
- | `OperationMetrics getMetrics()` | 返回一个包含该操作各项指标的对象。 |
- | `String getQueryId()` | 返回为该操作分配的查询 ID,该 ID 由应用程序(通过操作设置)指定或由服务器生成。 |
- | `TimeZone getTimeZone()` | 返回用于解析响应中 Date/DateTime 类型的时区。 |
+ | 方法 | 说明 |
+ | ------------------------------- | -------------------------------------------- |
+ | `ClickHouseFormat getFormat()` | 返回响应数据所使用的编码格式。 |
+ | `InputStream getInputStream()` | 返回以指定格式编码的未压缩数据字节流。 |
+ | `OperationMetrics getMetrics()` | 返回一个包含该操作各项指标的对象。 |
+ | `String getQueryId()` | 返回为该操作分配的查询 ID,该 ID 由应用程序(通过操作设置)指定,或由服务器生成。 |
+ | `TimeZone getTimeZone()` | 返回在解析响应中的 Date/DateTime 类型时应使用的时区。 |
### 示例 \{#examples\}
- * 示例代码可在该[代码仓库](https://github.com/ClickHouse/clickhouse-java/tree/main/examples/client-v2)中找到
- * 参考 Spring Service 的[实现示例](https://github.com/ClickHouse/clickhouse-java/tree/main/examples/demo-service)
+ * 示例代码可在[代码仓库](https://github.com/ClickHouse/clickhouse-java/tree/main/examples/client-v2)中获取
+ * 参考 Spring Service 的[实现](https://github.com/ClickHouse/clickhouse-java/tree/main/examples/demo-service)
## 通用 API \{#common-api\}
@@ -705,7 +743,7 @@ import WideTableWrapper from '@site/src/components/WideTableWrapper/WideTableWra
从 SQL 语句中获取 schema 信息。
- **方法签名**
+ **签名**
```java
TableSchema getTableSchemaFromQuery(String sql)
@@ -717,7 +755,7 @@ import WideTableWrapper from '@site/src/components/WideTableWrapper/WideTableWra
**返回值**
- 返回一个与 `sql` 表达式匹配列的 `TableSchema` 对象。
+ 返回一个列与 `sql` 表达式匹配的 `TableSchema` 对象。
### TableSchema \{#tableschema\}
@@ -726,7 +764,7 @@ import WideTableWrapper from '@site/src/components/WideTableWrapper/WideTableWra
为 Java 类编译一个序列化/反序列化层,以便在基于 `schema` 进行数据读写时使用。该方法将为 getter/setter 方法对及其对应的列创建序列化器和反序列化器。
列的匹配是通过从方法名中提取列名来完成的。例如,`getFirstName` 将对应列 `first_name` 或 `firstname`。
- **方法签名**
+ **签名**
```java
void register(Class> clazz, TableSchema schema)
@@ -748,17 +786,18 @@ import WideTableWrapper from '@site/src/components/WideTableWrapper/WideTableWra
完整示例代码存放在代码仓库的 'example` [文件夹](https://github.com/ClickHouse/clickhouse-java/tree/main/examples) 中:
- * [client-v2](https://github.com/ClickHouse/clickhouse-java/tree/main/examples/client-v2) - 主要示例集。
- * [demo-service](https://github.com/ClickHouse/clickhouse-java/tree/main/examples/demo-service) - 演示如何在 Spring Boot 应用中使用客户端的示例。
- * [demo-kotlin-service](https://github.com/ClickHouse/clickhouse-java/tree/main/examples/demo-kotlin-service) - 示例,演示如何在 Ktor(Kotlin)应用中使用该客户端。
+ * [client-v2](https://github.com/ClickHouse/clickhouse-java/tree/main/examples/client-v2) - 主要示例代码集。
+ * [demo-service](https://github.com/ClickHouse/clickhouse-java/tree/main/examples/demo-service) - 展示如何在 Spring Boot 应用中使用该客户端的示例。
+ * [demo-kotlin-service](https://github.com/ClickHouse/clickhouse-java/tree/main/examples/demo-kotlin-service) - 示例,用于展示如何在 Ktor(Kotlin)应用程序中使用该客户端。
## 读取数据 \{#reading-data\}
读取数据的常用方式有两种:
- * `query()` 方法会返回底层的 `QueryResponse` 对象,该对象包含承载数据的 `InputStream`。通常与 `ClickHouseBinaryFormatReader` 组合使用以进行流式读取,但也可以配合任何其他自定义 reader 实现使用。`QueryResponse` 还提供对结果集元数据和指标的访问能力。
- * `queryAll()` 方法并使用 `GenericRecord` 以便按行方便访问数据。在这种情况下,整个结果集会被一次性加载到内存中。
- * `queryRecords()` 方法返回 `com.clickhouse.client.api.query.Records` —— 一个用于迭代 `GenericRecord` 对象的迭代器。该方法采用流式处理方式(不会将全部数据加载到内存中),并利用 `GenericRecord` 来访问数据。
+ * `query()` 方法会返回底层的 `QueryResponse` 对象,该对象包含携带数据的 `InputStream`。通常与 `ClickHouseBinaryFormatReader` 组合使用以进行流式读取,但也可以配合任何其他自定义读取器实现使用。`QueryResponse` 还提供对结果集元数据和指标的访问能力。
+ * `queryAll()` 方法结合 `GenericRecord` 使用,可方便地按行访问数据。在这种情况下,整个结果集会被加载到内存中。
+ * `queryRecords()` 方法返回 `com.clickhouse.client.api.query.Records` —— 一种用于遍历 `GenericRecord` 对象的迭代器。该方法采用流式处理方式
+ (不会将数据加载到内存中),并使用 `GenericRecord` 来访问数据。
**注意:** 流式方法需要快速读取,否则可能导致服务器写入超时,因为数据是直接从网络流中读取的。
@@ -766,10 +805,10 @@ import WideTableWrapper from '@site/src/components/WideTableWrapper/WideTableWra
**`ClickHouseBinaryFormatReader` 方法**
- * `getList(...)` - 将任意 `Array(...)` 读取为 `List`。适合作为类型灵活读取的默认选项。支持嵌套数组。
- * `getByteArray(...)`, `getShortArray(...)`, `getIntArray(...)`, `getLongArray(...)`, `getFloatArray(...)`, `getDoubleArray(...)`, `getBooleanArray(...)` - 最适用于由与基本类型兼容的值构成的一维数组。
- * `getStringArray(...)` - 用于 `Array(String)`(以及以名称形式表示的枚举值)。
- * `getObjectArray(...)` - 适用于任意 `Array(...)` 元素类型(包括嵌套数组)的通用选项。用于读取包含 Nullable 值以及嵌套数组的数组。
+ * `getList(...)` - 将任意 `Array(...)` 读取为 `List`。适合作为灵活类型读取的默认方式。支持嵌套数组。
+ * `getByteArray(...)`, `getShortArray(...)`, `getIntArray(...)`, `getLongArray(...)`, `getFloatArray(...)`, `getDoubleArray(...)`, `getBooleanArray(...)` - 最适用于由与 Java 原始类型兼容的值组成的一维数组。
+ * `getStringArray(...)` - 用于 `Array(String)`(以及以名称表示的枚举值)。
+ * `getObjectArray(...)` - 适用于任意 `Array(...)` 元素类型(包括嵌套数组)的通用方法。用于读取包含 Nullable 值或嵌套数组的数组。
所有方法都提供基于索引和基于名称的重载。索引从 1 开始计数。基于索引的重载会直接访问对应的列。
基于名称的方法每次调用都需要执行一次索引查找。
@@ -791,13 +830,13 @@ import WideTableWrapper from '@site/src/components/WideTableWrapper/WideTableWra
**`GenericRecord` 方法**
- * `getList(...)` - 将任意 `Array(...)` 解析为 `List`。适合作为灵活类型读取的默认选项,支持嵌套数组。
+ * `getList(...)` - 将任意 `Array(...)` 读取为 `List`。适合作为进行灵活类型读取时的默认选择。支持嵌套数组。
* `getByteArray(...)`, `getShortArray(...)`, `getIntArray(...)`, `getLongArray(...)`, `getFloatArray(...)`, `getDoubleArray(...)`, `getBooleanArray(...)` - 最适用于由与原始类型兼容的值组成的一维数组。
- * `getStringArray(...)` - 用于 `Array(String)`(以及以名称表示的枚举类型值)。
- * `getObjectArray(...)` - 针对任意 `Array(...)` 元素类型(包括嵌套数组)的通用选项。用于读取包含 Nullable 值以及嵌套数组的数组。
+ * `getStringArray(...)` - 用于 `Array(String)`(以及以名称表示的枚举值)。
+ * `getObjectArray(...)` - 适用于任意 `Array(...)` 元素类型(包括嵌套数组)的通用选项。可用于读取包含 Nullable 值及嵌套数组的数组。
- 对于所有方法,都提供基于索引和基于名称的重载。索引从 1 开始。基于索引的重载直接访问列。
- 基于名称的方法每次都需要进行索引查找。
+ 所有方法都提供基于索引和基于名称的重载。索引从 1 开始计数。基于索引的重载会直接访问对应的列。
+ 基于名称的方法每次调用都需要执行一次索引查找。
````java
try (QueryResponse response = client.query("SELECT * FROM my_table").get()) {
@@ -1101,14 +1140,14 @@ import WideTableWrapper from '@site/src/components/WideTableWrapper/WideTableWra
}
```
- * 只需调用一个方法,无需单独创建请求对象。
- * 请求体数据流会在所有数据复制完成后自动关闭。
- * 现已提供新的低级 API:`com.clickhouse.client.api.Client#insert(java.lang.String, java.util.List, com.clickhouse.client.api.DataStreamWriter, com.clickhouse.data.ClickHouseFormat, com.clickhouse.client.api.insert.InsertSettings)`。`com.clickhouse.client.api.DataStreamWriter` 专为实现自定义数据写入逻辑而设计,例如从队列中读取数据。
+ * 只需要调用一个方法,无需另外创建请求对象。
+ * 当所有数据复制完成后,请求体数据流会自动关闭。
+ * 现已提供新的底层 API:`com.clickhouse.client.api.Client#insert(java.lang.String, java.util.List, com.clickhouse.client.api.DataStreamWriter, com.clickhouse.data.ClickHouseFormat, com.clickhouse.client.api.insert.InsertSettings)`。`com.clickhouse.client.api.DataStreamWriter` 用于实现自定义数据写入逻辑,例如用于从队列读取数据。
### 读取数据
- * 默认情况下,数据以 `RowBinaryWithNamesAndTypes` 格式读取。当需要进行数据绑定时,目前仅支持该格式。
- * 可以使用 `List com.clickhouse.client.api.Client#queryAll(java.lang.String)` 方法将数据读取为一组记录。该方法会将数据读入内存并释放连接,无需额外处理。`GenericRecord` 提供对数据的访问能力,并实现了一些类型转换。
+ * 默认情况下,数据以 `RowBinaryWithNamesAndTypes` 格式读取。在需要进行数据绑定时,目前仅支持该格式。
+ * 可以使用 `List com.clickhouse.client.api.Client#queryAll(java.lang.String)` 方法将数据读取为一组记录。该方法会将数据读取到内存并自动释放连接,无需额外处理。`GenericRecord` 提供对数据的访问能力,并实现了一些类型转换。
```java
Collection records = client.queryAll("SELECT * FROM table");
@@ -1301,8 +1340,8 @@ import WideTableWrapper from '@site/src/components/WideTableWrapper/WideTableWra
另外,您也可以通过以下几种方式禁用压缩。
- 1. 在连接 URL 中将 `compress` 设置为 `0` 即可禁用压缩:`http://localhost:8123/default?compress=0`
- 2. 在客户端配置中禁用:
+ 1. 通过在连接 URL 中将 `compress` 设置为 `0` 来禁用压缩:`http://localhost:8123/default?compress=0`
+ 2. 通过客户端配置禁用:
```java showLineNumbers
ClickHouseClient client = ClickHouseClient.builder()
@@ -1397,40 +1436,40 @@ import WideTableWrapper from '@site/src/components/WideTableWrapper/WideTableWra
以下选项用于自动发现相关配置:
- | 属性 | 默认值 | 描述 |
- | ------------------------------- | ------- | ----------------------------------------------------------- |
- | auto_discovery | `false` | 客户端是否应从 system 表以及/或 clickhouse-keeper/zookeeper 中自动发现更多节点。 |
- | node_discovery_interval | `0` | 以毫秒为单位的节点发现间隔,值为零或负数表示仅进行一次发现。 |
- | node_discovery_limit | `100` | 单次可发现的最大节点数;设置为零或负值表示不限制。 |
+ | 属性 | 默认值 | 描述 |
+ | ------------------------------- | ------- | ------------------------------------------------------------- |
+ | auto_discovery | `false` | 客户端是否应从 system 系统表以及/或 clickhouse-keeper/zookeeper 中自动发现更多节点。 |
+ | node_discovery_interval | `0` | 节点发现的时间间隔(毫秒),值为 0 或负数表示仅执行一次发现。 |
+ | node_discovery_limit | `100` | 单次可发现的最大节点数;设置为 0 或负值表示不限制。 |
### 负载均衡
Java 客户端根据负载均衡策略选择 ClickHouse 节点来发送请求。通常,负载均衡策略负责以下事项:
1. 从托管的节点列表中获取一个节点。
- 2. 管理节点的状态。
- 3. (可选)调度一个用于节点发现的后台进程(如果已启用自动发现),并执行健康检查。
+ 2. 管理节点状态。
+ 3. (可选)为节点发现(在启用自动发现的情况下)安排后台进程,并执行健康检查。
以下是配置负载均衡的选项列表:
- | 属性 | 默认值 | 描述 |
- | ----------------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
- | load_balancing_policy | `""` | 负载均衡策略可以是以下之一: `firstAlive` - 请求将被发送到受管节点列表中第一个健康节点 `random` - 请求将被发送到受管节点列表中随机选取的一个节点 `roundRobin` - 请求将按照轮询方式依次发送到受管节点列表中的每个节点 实现 `ClickHouseLoadBalancingPolicy` 的全限定类名 - 自定义负载均衡策略 如果未指定该策略,请求将被发送到受管节点列表中的第一个节点 |
- | load_balancing_tags | `""` | 用于筛选节点的负载均衡标签。只有具有指定标签的节点才会接收请求。 |
- | health_check_interval | `0` | 健康检查的时间间隔(毫秒)。值为 0 或负数表示只执行一次检查。 |
- | health_check_method | `ClickHouseHealthCheckMethod.SELECT_ONE` | 健康检查方法。可以是以下之一: `ClickHouseHealthCheckMethod.SELECT_ONE` - 通过 `select 1` 查询进行检查 `ClickHouseHealthCheckMethod.PING` - 协议特定的检查,通常更快 |
- | node_check_interval | `0` | 以毫秒为单位的节点检查间隔,负数将被视为 0。仅当自上次检查以来已过去指定的时间时,才会检查节点状态。 `health_check_interval` 和 `node_check_interval` 的区别在于,`health_check_interval` 选项会调度一个后台任务,对节点列表(全部节点或故障节点)执行状态检查,而 `node_check_interval` 则指定针对某个特定节点,自上次检查以来在再次检查前至少需要经过的时间间隔。 |
- | check_all_nodes | `false` | 是否对所有节点执行健康检查,还是仅对故障节点执行检查。 |
+ | 属性 | 默认值 | 描述 |
+ | ----------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+ | load_balancing_policy | `""` | 负载均衡策略可以是以下之一: `firstAlive` - 请求将被发送到受管节点列表中第一个健康节点 `random` - 请求将被发送到受管节点列表中随机选取的一个节点 `roundRobin` - 请求将按照轮询方式依次发送到受管节点列表中的每个节点 实现 `ClickHouseLoadBalancingPolicy` 的完整限定类名 - 自定义负载均衡策略 如果未指定该策略,请求将被发送到受管节点列表中的第一个节点 |
+ | load_balancing_tags | `""` | 用于筛选节点的负载均衡标签。只有具有指定标签的节点才会接收请求。 |
+ | health_check_interval | `0` | 健康检查的时间间隔(毫秒)。值为 0 或负数表示只执行一次检查。 |
+ | health_check_method | `ClickHouseHealthCheckMethod.SELECT_ONE` | 健康检查方法。可以是以下之一: `ClickHouseHealthCheckMethod.SELECT_ONE` - 通过 `select 1` 查询进行检查 `ClickHouseHealthCheckMethod.PING` - 基于协议的检查,通常更快 |
+ | node_check_interval | `0` | 以毫秒为单位的节点检查间隔,负数将被视为 0。仅当自上次检查以来已过去指定的时间时,才会检查该节点的状态。 `health_check_interval` 和 `node_check_interval` 的区别在于,`health_check_interval` 选项会调度一个后台任务,对节点列表(全部节点或故障节点)执行状态检查,而 `node_check_interval` 则指定针对某个特定节点,自上次检查以来在再次检查前至少需要经过的时间间隔。 |
+ | check_all_nodes | `false` | 是否对所有节点执行健康检查,还是仅对故障节点执行检查。 |
### 故障转移和重试
Java 客户端提供一些配置选项,用于配置故障转移和失败查询的重试行为:
- | 参数 | 默认值 | 说明 |
- | ---------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------- |
- | failover | `0` | 针对单个请求允许执行故障转移的最大次数。值为 0 或负数表示不进行故障转移。发生故障转移时,客户端会根据负载均衡策略将失败的请求发送到其他节点,以从故障中恢复。 |
- | retry | `0` | 单个请求允许重试的最大次数。为零或负值时表示不进行重试。重试时,请求会发送到同一节点,并且仅当 ClickHouse 服务器返回 `NETWORK_ERROR` 错误码时才会执行重试。 |
- | repeat_on_session_lock | `true` | 当会话被锁定时,是否重复执行直到会话超时(超时时间由 `session_timeout` 或 `connect_timeout` 决定)。如果 ClickHouse 服务器返回 `SESSION_IS_LOCKED` 错误码,则会重试该失败请求。 |
+ | 参数 | 默认值 | 说明 |
+ | ---------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------- |
+ | failover | `0` | 针对单个请求允许执行故障转移的最大次数。值为 0 或负数表示不进行故障转移。发生故障转移时,客户端会根据负载均衡策略将失败的请求发送到其他节点,以从故障中恢复。 |
+ | retry | `0` | 单个请求允许重试的最大次数。为零或负值时表示不进行重试。发生重试时,请求会发送到同一节点,并且仅在 ClickHouse 服务器返回 `NETWORK_ERROR` 错误码时才会进行重试 |
+ | repeat_on_session_lock | `true` | 当会话被锁定时,是否重复执行直到会话超时(超时时间由 `session_timeout` 或 `connect_timeout` 决定)。如果 ClickHouse 服务器返回 `SESSION_IS_LOCKED` 错误码,则会对该失败请求进行重试 |
### 添加自定义 HTTP 请求头
diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/integrations/language-clients/java/jdbc/jdbc.mdx b/i18n/zh/docusaurus-plugin-content-docs/current/integrations/language-clients/java/jdbc/jdbc.mdx
index a40814d1b2d..20b41afd1f8 100644
--- a/i18n/zh/docusaurus-plugin-content-docs/current/integrations/language-clients/java/jdbc/jdbc.mdx
+++ b/i18n/zh/docusaurus-plugin-content-docs/current/integrations/language-clients/java/jdbc/jdbc.mdx
@@ -70,9 +70,9 @@ import TabItem from '@theme/TabItem';
如果您在应用程序中使用 JDBC 驱动程序,且该应用程序需要将 jar 添加到 classpath,则需要从以下地址下载 jar 文件:
* 从 [Maven Central](https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc) 下载并将其添加到 classpath 中
- * 从版本 `0.9.4` 开始,提供了构建产物 https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc-all
- * 使用限定符 `all` 以获取包含所有已打包(shaded)依赖的 JAR。
- * 或从官方仓库[此处](https://github.com/ClickHouse/clickhouse-java/releases)获取
+ * 从版本 `0.9.4` 开始,新增了构件 https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc-all
+ * 使用限定符 `all` 以获取包含所有打包(shaded)依赖的 jar。
+ * 或从官方仓库[此处](https://github.com/ClickHouse/clickhouse-java/releases)下载
## 配置 \{#configuration\}
@@ -94,10 +94,10 @@ import TabItem from '@theme/TabItem';
关于 URL 语法,有以下几点需要注意:
- * URL 中**只能**包含一个 endpoint
- * 当使用的协议不是默认的 HTTP 协议时,应显式指定协议
+ * URL 中 **只能** 指定一个 endpoint
+ * 当所用协议不是默认的 HTTP 时,应显式指定协议
* 如果端口不是默认的 '8123',则必须显式指定。
- * 驱动程序不会根据端口来推断协议,你需要显式指定协议
+ * 驱动程序不会根据端口推断协议,因此必须显式指定协议
* 如果已指定协议,则无需设置 `ssl` 参数。
### 连接属性 \{#connection-properties\}
@@ -109,14 +109,14 @@ import TabItem from '@theme/TabItem';
| 属性 | 默认值 | 描述 |
| ----------------------------------- | -------- | ---------------------------------------------------------------------------------- |
| `disable_frameworks_detection` | `true` | 禁用基于 User-Agent 的框架识别 |
- | `jdbc_ignore_unsupported_values` | `false` | 在不影响驱动工作的情况下抑制 `SQLFeatureNotSupportedException` 异常 |
+ | `jdbc_ignore_unsupported_values` | `false` | 在不影响驱动正常工作的情况下抑制抛出 `SQLFeatureNotSupportedException` 异常 |
| `clickhouse.jdbc.v1` | `false` | 使用旧版 JDBC 实现,而不是新版实现 |
| `default_query_settings` | `null` | 允许在执行查询时传递默认查询设置 |
- | `jdbc_resultset_auto_close` | `true` | 在关闭 `Statement` 时自动关闭 `ResultSet` |
+ | `jdbc_resultset_auto_close` | `true` | 当 `Statement` 关闭时自动关闭 `ResultSet` |
| `beta.row_binary_for_simple_insert` | `false` | 使用基于 `RowBinary` writer 的 `PreparedStatement` 实现,仅适用于 `INSERT INTO ... VALUES` 查询。 |
| `jdbc_resultset_auto_close` | `true` | `Statement` 关闭时自动关闭 `ResultSet` |
- | `jdbc_use_max_result_rows` | `false` | 启用后,将使用服务器端属性 `max_result_rows` 来限制查询返回的行数。启用该选项时,会覆盖用户设置的溢出模式。详细信息请参见 JavaDoc。 |
- | `jdbc_sql_parser` | `JAVACC` | 配置要使用的 SQL 解析器类型。可选值为:`ANTLR4`、`ANTLR4_PARAMS_PARSER`、`JAVACC`。 |
+ | `jdbc_use_max_result_rows` | `false` | 启用后,将使用服务器属性 `max_result_rows` 来限制查询返回的行数。启用该选项时,会覆盖用户配置的溢出模式。详细信息请参见 JavaDoc。 |
+ | `jdbc_sql_parser` | `JAVACC` | 配置要使用的 SQL 解析器。可选值为:`ANTLR4`、`ANTLR4_PARAMS_PARSER`、`JAVACC`。 |
:::note 服务器设置
@@ -155,6 +155,39 @@ import TabItem from '@theme/TabItem';
注意:无需对 JDBC URL 或属性进行 URL 编码,系统将自动进行编码。
+ ### 客户端标识 \{#client-identification\}
+
+ 有两种方式可以标识发起请求的应用程序:通过连接属性设置 `com.clickhouse.client.api.ClientConfigProperties#CLIENT_NAME`,或使用 `java.sql.Connection#setClientInfo(String name, String value)` 方法。
+
+ ```java showLineNumbers
+ Properties properties = new Properties();
+ properties.setProperty(ClientConfigProperties.CLIENT_NAME.getKey(), "my-app-01");
+ Connection conn = Driver.connect("jdbc:ch:http://localhost:8123/", properties);
+ ```
+
+ ```java showLineNumbers
+ conn.setClientInfo(com.clickhouse.jdbc.ClientInfoProperties.APPLICATION_NAME.getKey(), "my-app-01");
+ ```
+
+ 两种方式都会在查询日志中生成以下 `http_user_agent` 值:
+
+ ```
+ my-app-01/1.0 clickhouse-java-v2/0.9.6-SNAPSHOT (Linux; jvm:17.0.17) Apache-HttpClient/5.4.4
+ ```
+
+ ### 操作标识 \{#operation-identification\}
+
+ JDBC 驱动程序会为每个操作生成 `query_id`(目前该信息包含在服务器异常中)。
+
+ 要为某个操作设置 `log_comment`,请使用 `com.clickhouse.jdbc.StatementImpl#getLocalSettings` 方法。这需要先将 `Statement` 或 `PreparedStatement` 强制转换为 `com.clickhouse.jdbc.StatementImpl`。
+
+ ```java showLineNumbers
+ StatementImpl stmt = (StatementImpl) conn.createStatement();
+ stmt.getLocalSettings().logComment("some-comment");
+ ```
+
+ **注意:** 此方法适用于语句的单线程使用场景,因为 `localSettings` 在线程间是共享的。
+
## 支持的数据类型 \{#supported-data-types\}
JDBC 驱动支持与底层 [Java 客户端](/integrations/java#supported-data-types)相同的数据格式。
@@ -168,7 +201,7 @@ import TabItem from '@theme/TabItem';
有几种方法可以更改映射:
- * `ResultSet#getObject(columnIndex, class)` - 该方法会尝试将值转换为指定的 `class` 类型。此类转换存在一定限制。详细情况请参阅各节说明。
+ * `ResultSet#getObject(columnIndex, class)` - 该方法会尝试将该值转换为指定的 `class` 类型。此类转换存在一定限制。详细情况请参阅各节说明。
**数值类型**
@@ -194,13 +227,13 @@ import TabItem from '@theme/TabItem';
| Decimal256 | DECIMAL | java.math.BigDecimal |
| Bool | BOOLEAN | java.lang.Boolean |
- * 数值类型之间可以相互转换。因此,可以将 `Int8` 作为 `Float64` 获取,反之亦然。:
+ * 数值类型之间可以相互转换。因此,可以将 `Int8` 读取为 `Float64`,反之亦然:
* `rs.getObject(1, Float64.class)` 将返回 `Int8` 列的 `Float64` 值。
* `rs.getLong(1)` 将返回 `Int8` 列的 `Long` 值。
* 如果值在 `Byte` 的取值范围内,`rs.getByte(1)` 可以返回 `Int16` 列的 `Byte` 值。
- * 由于存在数据损坏风险,不建议将更宽类型转换为更窄类型。
- * `Bool` 类型也可以作为数值使用。
- * 所有数值类型都可以读取为 `java.lang.String`。
+ * 由于存在数据损坏风险,不建议进行从更宽类型到更窄类型的转换,以免产生数据损坏。
+ * `Bool` 类型也可以当作数值类型使用。
+ * 所有数值类型都可以作为 `java.lang.String` 读取。
**字符串类型**
@@ -209,8 +242,8 @@ import TabItem from '@theme/TabItem';
| String | VARCHAR | java.lang.String |
| FixedString | VARCHAR | java.lang.String |
- * `String` 只能被读取为 `java.lang.String` 或 `byte[]` 类型。
- * `FixedString` 在读取时会保持原样,并在末尾用零字节补齐到该列的长度。(例如,将 `'John'` 存储为 `FixedString(10)` 时,读取结果为 `'John\0\0\0\0\0\0\0\0\0'`。)
+ * `String` 只能以 `java.lang.String` 或 `byte[]` 的形式读取。
+ * `FixedString` 读取时按原样返回,并在末尾用零字节补齐至该列的长度。(例如,将 `'John'` 定义为 `FixedString(10)` 时,读取结果为 `'John\0\0\0\0\0\0\0\0\0'`。)
**枚举类型**
@@ -220,9 +253,9 @@ import TabItem from '@theme/TabItem';
| Enum16 | OTHER | java.lang.String |
* `Enum8` 和 `Enum16` 默认映射为 `java.lang.String`。
- * 枚举值可以通过相应的数值型 getter 方法,或使用 `getObject(columnIndex, Integer.class)` 方法,以数值形式读取。
- * `Enum16` 在内部映射为 short,而 `Enum8` 映射为 byte。应避免将 `Enum16` 按 byte 读取,否则有导致数据损坏的风险。
- * 可以在 `PreparedStatement` 中将枚举值设置为字符串值或数值。
+ * 枚举值可以通过相应的数值型 getter 方法或使用 `getObject(columnIndex, Integer.class)` 方法读取为数值。
+ * `Enum16` 在内部映射为 short 类型,而 `Enum8` 映射为 byte 类型。应避免将 `Enum16` 以 byte 形式读取,否则存在数据损坏风险。
+ * 可以在 `PreparedStatement` 中以字符串或数值形式设置枚举值。
**日期/时间类型**
@@ -235,13 +268,13 @@ import TabItem from '@theme/TabItem';
| Time | TIME | java.sql.Time |
| Time64 | TIME | java.sql.Time |
- * 日期/时间类型会映射为 `java.sql` 类型,以便更好地兼容 JDBC。但仍然可以通过调用 `ResultSet#getObject(columnIndex, Class)`,并将相应的类作为第二个参数来获取 `java.time.LocalDate`、`java.time.LocalDateTime`、`java.time.LocalTime`。
- * `rs.getObject(1, java.time.LocalDate.class)` 将返回 `Date` 列中对应的 `java.time.LocalDate` 值。
- * `rs.getObject(1, java.time.LocalDateTime.class)` 将返回 `DateTime` 列中对应的 `java.time.LocalDateTime` 值。
- * `rs.getObject(1, java.time.LocalTime.class)` 将返回 `Time` 列中对应的 `java.time.LocalTime` 值。
- * `Date`、`Date32`、`Time`、`Time64` 不受服务器的时区影响。
- * `DateTime`、`DateTime64` 受服务器时区或会话时区影响。
- * `DateTime` 和 `DateTime64` 可以通过 `getObject(colIndex, ZonedDateTime.class)` 以 `ZonedDateTime` 的形式获取。
+ * 日期/时间类型会映射为 `java.sql` 类型,以便与 JDBC 有更好的兼容性。不过,仍然可以通过调用 `ResultSet#getObject(columnIndex, Class)`,并将相应的类作为第二个参数传入,来获取 `java.time.LocalDate`、`java.time.LocalDateTime`、`java.time.LocalTime`。
+ * `rs.getObject(1, java.time.LocalDate.class)` 将返回 `Date` 列的 `java.time.LocalDate` 值。
+ * `rs.getObject(1, java.time.LocalDateTime.class)` 将返回 `DateTime` 列的 `java.time.LocalDateTime` 值。
+ * `rs.getObject(1, java.time.LocalTime.class)` 将返回 `Time` 列的 `java.time.LocalTime` 值。
+ * `Date`, `Date32`, `Time`, `Time64` 不会受到服务器时区的影响。
+ * `DateTime`、`DateTime64` 会受到服务器时区或会话时区的影响。
+ * `DateTime` 和 `DateTime64` 可以通过 `getObject(colIndex, ZonedDateTime.class)` 获取为 `ZonedDateTime` 对象。
**嵌套类型**
@@ -252,13 +285,13 @@ import TabItem from '@theme/TabItem';
| Map | JAVA_OBJECT | java.util.Map |
| Nested | ARRAY | java.sql.Array |
- * `Array` 默认会映射为 `java.sql.Array`,以保证与 JDBC 的兼容性。这也能提供关于返回的数组值的更多信息,有助于进行类型推断。
- * `Array` 实现了 `getResultSet()` 方法,以返回内容与原始数组相同的 `java.sql.ResultSet` 对象。
- * 集合类型不应被读取为 `java.lang.String`,因为这样无法正确表示数据(例如:数组中的字符串值不会被加引号)。
- * `Map` 映射为 `JAVA_OBJECT`,因为其值只能通过 `getObject(columnIndex, Class)` 方法读取。
+ * `Array` 默认会映射为 `java.sql.Array`,以保证与 JDBC 的兼容性。这样也能提供更多关于返回数组值的信息,有助于进行类型推断。
+ * `Array` 实现了 `getResultSet()` 方法,以返回一个内容与原始数组相同的 `java.sql.ResultSet`。
+ * 集合类型不应被读取为 `java.lang.String`,因为那并不是一种有效的数据表示方式(例如:数组中的字符串值不会被加上引号)。
+ * `Map` 映射为 `JAVA_OBJECT`,因为其中的值只能通过 `getObject(columnIndex, Class)` 方法读取。
* `Map` 不是 `java.sql.Struct`,因为它没有具名列。
- * `Tuple` 映射为 `Object[]`,因为它可以包含不同类型的元素,使用 `List` 作为映射类型是不合法的。
- * `Tuple` 可以通过 `getObject(columnIndex, Array.class)` 方法读取为 `Array` 类型。在这种情况下,`Array#baseTypeName` 将返回该 `Tuple` 列的定义。
+ * `Tuple` 映射为 `Object[]`,因为它可以包含不同类型的元素,使用 `List` 进行映射是无效的。
+ * `Tuple` 可以通过 `getObject(columnIndex, Array.class)` 方法被读取为 `Array` 类型。在这种情况下,`Array#baseTypeName` 会返回 `Tuple` 列的定义。
**写入数组**
@@ -267,8 +300,8 @@ import TabItem from '@theme/TabItem';
该方法接受两个参数:
- * `typeName` - 数组元素的类型名称。例如 `Array(Int32)` -> `"Int32"`。
- * `elements` - 数组中的实际元素。例如 `[[1, 2, 3], [4, 5, 6]]` -> `new Integer[][] {{1, 2, 3}, {4, 5, 6}}`。
+ * `typeName` - 数组元素类型的名称。例如 `Array(Int32)` -> `"Int32"`。
+ * `elements` - 数组的实际元素。例如 `[[1, 2, 3], [4, 5, 6]]` -> `new Integer[][] {{1, 2, 3}, {4, 5, 6}}`。
Tuple 可以表示为 `Object[]` 或 `java.sql.Struct`(请参阅下文中关于如何写入 Tuple 的说明)。
@@ -406,8 +439,8 @@ import TabItem from '@theme/TabItem';
该方法接受两个参数:
- * `typeName` - 嵌套元素类型的名称。例如 `Nested(Tuple(Int32, String))` -> `"Nested(Tuple(Int32, String))"`。
- * `elements` - 实际的嵌套元素本身。例如 `[1, 'test']` -> `new Object[] {1, 'test'}`。
+ * `typeName` - 嵌套元素的类型名称。例如 `Nested(Tuple(Int32, String))` -> `"Nested(Tuple(Int32, String))"`。
+ * `elements` - 实际的嵌套元素。例如 `[1, 'test']` -> `new Object[] {1, 'test'}`。
**示例**
@@ -460,8 +493,8 @@ import TabItem from '@theme/TabItem';
**Nullable 和 LowCardinality 类型**
- * `Nullable` 和 `LowCardinality` 是用于封装其他类型的特殊类型。
- * `Nullable` 会影响 `ResultSetMetaData` 中类型名称的返回方式
+ * `Nullable` 和 `LowCardinality` 是包装其他类型的特殊类型。
+ * `Nullable` 会影响 `ResultSetMetaData` 返回的类型名称
**特殊类型**
@@ -474,10 +507,10 @@ import TabItem from '@theme/TabItem';
| AggregateFunction | OTHER | (二进制表示) |
| SimpleAggregateFunction | (封装类型) | (封装类) |
- * `UUID` 不是 JDBC 标准类型,但它是 JDK 的一部分。默认情况下,通过 `getObject()` 方法会返回一个 `java.util.UUID` 实例。
- * 可以使用 `getObject(columnIndex, String.class)` 方法以 `String` 形式对 `UUID` 进行读写。
+ * `UUID` 不是 JDBC 标准类型,但它是 JDK 的一部分。默认情况下,调用 `getObject()` 方法会返回一个 `java.util.UUID` 实例。
+ * 可以使用 `getObject(columnIndex, String.class)` 方法,以 `String` 形式读取和写入 `UUID`。
* `IPv4` 和 `IPv6` 不是 JDBC 标准类型,但它们是 JDK 的一部分。默认情况下,调用 `getObject()` 方法时会返回 `java.net.Inet4Address` 和 `java.net.Inet6Address` 实例。
- * 通过 `getObject(columnIndex, String.class)` 方法,`IPv4` 和 `IPv6` 可以以 `String` 形式进行读写。
+ * 通过 `getObject(columnIndex, String.class)` 方法,可以将 `IPv4` 和 `IPv6` 作为 `String` 进行读写。
### 处理日期、时间和时区 \{#handling-dates-times-and-timezones\}
@@ -603,7 +636,7 @@ import TabItem from '@theme/TabItem';
在 Linux 上,仅配置等效设置可能无法解决问题。由于 Linux 处理套接字 keep-alive 设置的方式不同,需要执行额外的步骤。请按照以下步骤操作:
- 1. 在 `/etc/sysctl.conf` 或其他相关配置文件中调整以下 Linux 内核参数:
+ 1. 在 `/etc/sysctl.conf` 或其他相关的配置文件中调整以下 Linux 内核参数:
* `net.inet.tcp.keepidle`: 60000
* `net.inet.tcp.keepintvl`: 45000
@@ -612,7 +645,7 @@ import TabItem from '@theme/TabItem';
* `net.inet.tcp.always_keepalive`: 1
* `net.ipv4.tcp_keepalive_intvl`: 75
* `net.ipv4.tcp_keepalive_probes`: 9
- * `net.ipv4.tcp_keepalive_time`: 60(可以考虑将该值从默认值 300 秒适当调低)
+ * `net.ipv4.tcp_keepalive_time`: 60(可考虑将该值从默认的 300 秒降低)
2. 修改内核参数后,运行以下命令以使更改生效:
@@ -633,28 +666,28 @@ import TabItem from '@theme/TabItem';
| 功能 | V1(旧版) | V2(新版) |
| ------------------------------- | ------ | --------------- |
| 事务支持 | 部分支持 | 不支持 |
- | 响应中列重命名 | 部分支持 | 不支持 |
+ | 响应中的列重命名 | 部分支持 | 不支持 |
| 多语句 SQL | 不支持 | 不允许 |
| 命名参数 | 支持 | 不支持(JDBC 规范未定义) |
| 使用 `PreparedStatement` 进行流式数据传输 | 支持 | 不支持 |
- * JDBC V2 采用了更轻量的实现,因此移除了部分功能。
- * JDBC V2 不支持流式数据传输,因为该特性既不是 JDBC 规范的一部分,也不是 Java 标准的一部分。
- * JDBC V2 需要显式配置,不提供任何故障转移相关的默认设置。
+ * JDBC V2 为了更加轻量化而实现,因此移除了一些功能。
+ * JDBC V2 不支持流式数据传输,因为该功能既不在 JDBC 规范中定义,也未在 Java 中定义。
+ * JDBC V2 需要显式配置,不提供任何故障转移默认配置。
* 协议应在 URL 中显式指定,不进行基于端口号的隐式协议推断。
### 配置更改 \{#configuration-changes\}
仅有两个枚举:
- * `com.clickhouse.jdbc.DriverProperties` - 驱动程序自身的配置属性。
- * `com.clickhouse.client.api.ClientConfigProperties` - 客户端的配置属性。关于客户端配置变更,详见 [Java Client 文档](/integrations/language-clients/java/client/client.mdx#migration_from_v1_config)。
+ * `com.clickhouse.jdbc.DriverProperties` - 驱动程序特有的配置属性。
+ * `com.clickhouse.client.api.ClientConfigProperties` - 客户端配置属性。客户端配置变更详见 [Java Client 文档](/integrations/language-clients/java/client/client.mdx#migration_from_v1_config)。
连接属性按以下方式解析:
- * URL 首先会被解析以提取属性,这些属性会覆盖所有其他属性。
- * 驱动属性不会被传递给客户端。
- * 端点信息(主机、端口、协议)从 URL 中解析而来。
+ * 会首先从 URL 中解析出属性,这些属性将覆盖所有其他属性。
+ * 驱动程序属性不会传递给客户端。
+ * 端点(主机、端口、协议)从 URL 中解析得到。
示例:
@@ -676,7 +709,7 @@ import TabItem from '@theme/TabItem';
**数值类型**
- | ClickHouse 类型 | 是否与 V1 兼容 | JDBC 类型(V2) | Java 类(V2) | JDBC 类型(V1) | Java 类(V1) |
+ | ClickHouse 类型 | 与 V1 的兼容性 | JDBC 类型(V2) | Java 类(V2) | JDBC 类型(V1) | Java 类(V1) |
| ------------- | --------- | ----------- | -------------------- | ----------- | ----------------------------------------- |
| Int8 | ✅ | TINYINT | java.lang.Byte | TINYINT | java.lang.Byte |
| Int16 | ✅ | SMALLINT | java.lang.Short | SMALLINT | java.lang.Short |
@@ -698,7 +731,7 @@ import TabItem from '@theme/TabItem';
| Decimal256 | ✅ | DECIMAL | java.math.BigDecimal | DECIMAL | java.math.BigDecimal |
| Bool | ✅ | BOOLEAN | java.lang.Boolean | BOOLEAN | java.lang.Boolean |
- * 主要区别在于,现在会将无符号类型映射为 Java 类型,以提高可移植性。
+ * 最大的区别在于,将无符号类型映射为 Java 类型,以提高可移植性。
**字符串类型**
@@ -708,22 +741,22 @@ import TabItem from '@theme/TabItem';
| FixedString | ✅ | VARCHAR | java.lang.String | VARCHAR | java.lang.String |
* `FixedString` 在两个版本中均按原样读取。例如,对于 `'John'`,`FixedString(10)` 会被读取为 `'John\0\0\0\0\0\0\0\0\0'`。
- * 当使用 `PreparedStatement#setBytes` 时,会先将该值转换为 `unhex('')`,然后按 `String` 类型读取。
+ * 当使用 `PreparedStatement#setBytes` 时,会被转换为 `unhex('')`,然后作为 `String` 类型读取。
* 字符串以 UTF-8 编码存储。
**日期/时间类型**
- | ClickHouse 类型 | 是否与 V1 兼容 | JDBC 类型(V2) | Java 类(V2) | JDBC 类型(V1) | Java 类(V1) |
+ | ClickHouse 类型 | 是否与 V1 兼容 | JDBC 类型(V2) | Java 类(V2) | JDBC 类型(V1) | Java 类(V1) |
| ------------- | --------- | ----------- | ------------------ | ----------- | ------------------------ |
| Date | ❌ | DATE | java.sql.Date | DATE | java.time.LocalDate |
| Date32 | ❌ | DATE | java.sql.Date | DATE | java.time.LocalDate |
| DateTime | ❌ | TIMESTAMP | java.sql.Timestamp | TIMESTAMP | java.time.OffsetDateTime |
| DateTime64 | ❌ | TIMESTAMP | java.sql.Timestamp | TIMESTAMP | java.time.OffsetDateTime |
| Time | ✅ | TIME | java.sql.Time | 新类型/不支持 | 新类型/不支持 |
- | Time64 | ✅ | TIME | java.sql.Time | 新类型/不支持 | 新类型 / 不支持 |
+ | Time64 | ✅ | TIME | java.sql.Time | 新类型/未支持 | 新类型 / 未支持 |
- * `Time` 和 `Time64` 仅在 V2 中作为新增类型得到支持。
- * `DateTime` 和 `DateTime64` 被映射为 `java.sql.Timestamp`,以实现更好的 JDBC 兼容性。
+ * `Time` 和 `Time64` 仅作为新类型在 V2 中受支持。
+ * `DateTime` 和 `DateTime64` 映射到 `java.sql.Timestamp` 类型,以提高与 JDBC 的兼容性。
**枚举类型**
@@ -742,15 +775,15 @@ import TabItem from '@theme/TabItem';
| Map | ❌ | JAVA_OBJECT | java.util.Map | STRUCT | java.util.Map |
| Nested | ❌ | ARRAY | java.sql.Array | STRUCT | java.sql.Struct |
- * 在 V2 中,`Array` 默认映射为 `java.sql.Array`,以便与 JDBC 保持兼容。这也能提供更多关于返回数组值的信息,有利于进行类型推断。
- * 在 V2 中,`Array` 实现了 `getResultSet()` 方法,以返回一个内容与原始数组相同的 `java.sql.ResultSet` 对象。
+ * 在 V2 中,`Array` 默认映射为 `java.sql.Array`,以便与 JDBC 保持兼容。这样做也能提供更多关于返回数组值的信息,有助于进行类型推断。
+ * 在 V2 中,`Array` 实现了 `getResultSet()` 方法,用于返回一个内容与原始数组相同的 `java.sql.ResultSet`。
* V1 对 `Map` 使用 `STRUCT`,但始终返回 `java.util.Map` 对象。V2 通过将 `Map` 映射为 `JAVA_OBJECT` 解决了这一问题。
- * V1 将 `Tuple` 映射为 `STRUCT`,但始终返回 `List` 对象。V2 将 `Tuple` 映射为 `OTHER`,并默认返回 `Object[]` 数组。
- * V2 引入了 `com.clickhouse.data.Tuple#Tuple` 用于写入 Tuple 值。它简化了判断某个值是 Tuple 还是数组的过程。
- * `PreparedStatement#setBytes` 和 `ResultSet#getBytes` 不能与集合类型一起使用。这些方法是专为处理二进制字符串而设计的。
- * 通常会使用 `java.sql.Array` 来写入和读取 Array 类型。JDBC 驱动对这一点提供了完整支持。
- * 在 V2 中,`Nested` 被映射为 `Array`,并将其表示为元组数组。
- * V2 对 `java.sql.Struct` 提供了部分支持,由于它与 Array 类型非常相似,本身不支持键值对。`Struct` 可用于写入 `Tuple` 类型的值。
+ * V1 将 `Tuple` 映射为 `STRUCT`,但始终返回 `List<Object>`。V2 将 `Tuple` 映射为 `OTHER`,并默认返回 `Object[]`。
+ * V2 引入了 `com.clickhouse.data.Tuple#Tuple` 用于写入 Tuple。这样可以更容易判断某个值是 Tuple 还是数组。
+ * `PreparedStatement#setBytes` 和 `ResultSet#getBytes` 不能用于集合类型。这些方法是专为处理二进制字符串而设计的。
+ * 通常使用 `java.sql.Array` 来写入和读取 Array 类型。JDBC 驱动对此提供了完整支持。
+ * 在 V2 中,`Nested` 被映射为 `Array`,并将其呈现为由元组组成的数组。
+ * V2 对 `java.sql.Struct` 提供了部分支持,因为它与 Array 类型非常相似,而且不支持键值对。`Struct` 可用于写入 `Tuple` 类型的值。
**地理类型**
@@ -763,7 +796,7 @@ import TabItem from '@theme/TabItem';
**Nullable 和 LowCardinality 类型**
- * `Nullable` 和 `LowCardinality` 是包装其他类型的特殊类型。
+ * `Nullable` 和 `LowCardinality` 是用于封装其他类型的特殊类型。
* 在 V2 中,这些类型没有变化。
**特殊类型**
@@ -776,20 +809,20 @@ import TabItem from '@theme/TabItem';
| UUID | ✅ | OTHER | java.util.UUID | VARCHAR | java.util.UUID |
| IPv4 | ✅ | OTHER | java.net.Inet4Address | VARCHAR | java.net.Inet4Address |
| IPv6 | ✅ | OTHER | java.net.Inet6Address | VARCHAR | java.net.Inet6Address |
- | Dynamic | ❌ | OTHER | java.lang.Object | 不支持 | 不支持 |
- | Variant | ❌ | OTHER | java.lang.Object | 不支持 | 不支持 |
+ | Dynamic | ❌ | OTHER | java.Object | 不支持 | 不支持 |
+ | Variant | ❌ | OTHER | java.Object | 不支持 | 不支持 |
- * V1 使用 `VARCHAR` 作为 `UUID` 的 JDBC 类型,但始终返回 `java.util.UUID` 对象。V2 通过将 `UUID` 映射为 `OTHER`,并同样返回 `java.util.UUID` 对象来修复此问题。
- * V1 对 `IPv4` 和 `IPv6` 使用 `VARCHAR` 类型,但始终返回 `java.net.Inet4Address` 和 `java.net.Inet6Address` 对象。V2 通过将 `IPv4` 和 `IPv6` 映射为 JDBC 类型 `OTHER`,并返回 `java.net.Inet4Address` 和 `java.net.Inet6Address` 对象以此修复该问题。
+ * V1 使用 `VARCHAR` 作为 `UUID` 的 JDBC 类型,但始终返回 `java.util.UUID` 对象。V2 通过将 `UUID` 映射为 `OTHER`,并仍然返回 `java.util.UUID` 对象来修复此问题。
+ * V1 对 `IPv4` 和 `IPv6` 使用 `VARCHAR` 类型,但始终返回 `java.net.Inet4Address` 和 `java.net.Inet6Address` 对象。V2 通过将 `IPv4` 和 `IPv6` 映射为 JDBC 类型 `OTHER`,并返回 `java.net.Inet4Address` 和 `java.net.Inet6Address` 对象来修复此问题。
* `Dynamic` 和 `Variant` 是 V2 中新增的类型,在 V1 中不支持。
- * `JSON` 基于 `Dynamic` 类型,因此仅在 V2 中受支持。
+ * `JSON` 基于 `Dynamic` 类型,因此仅在 V2 中提供支持。
* 可以通过 `getBytes(columnIndex)` 方法将 IPv4 和 IPv6 的值读取为 `byte[]`。不过,建议针对这些类型使用专门的类。
* V2 不支持以数值形式读取 IP 地址,因为在 InetAddress 类中完成该转换的实现更为合理。
### 数据库元数据变更 \{#database-metadata-changes\}
- * V2 仅使用 `Schema` 一词来表示数据库。`Catalog` 一词保留供将来使用。
- * V2 会在 `DatabaseMetaData.supportsTransactions()` 和 `DatabaseMetaData.supportsSavepoints()` 中返回 `false`。这一行为将在后续版本的开发中进行调整。
+ * V2 仅使用 `Schema` 这一术语来表示数据库,将 `Catalog` 术语保留作今后使用。
+ * V2 会在 `DatabaseMetaData.supportsTransactions()` 和 `DatabaseMetaData.supportsSavepoints()` 中返回 `false`。这一行为将在后续版本中进行调整。
@@ -881,12 +914,12 @@ import TabItem from '@theme/TabItem';
| 属性 | 默认值 | 说明 |
| -------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
- | `continueBatchOnError` | `false` | 是否在发生错误时继续执行后续批处理操作 |
+ | `continueBatchOnError` | `false` | 出错后是否继续执行后续批处理 |
| `createDatabaseIfNotExist` | `false` | 当目标数据库不存在时是否自动创建 |
| `custom_http_headers` | | 以逗号分隔的自定义 HTTP 请求头,例如:`User-Agent=client1,X-Gateway-Id=123` |
- | `custom_http_params` | | 用逗号分隔的自定义 HTTP 查询参数,例如:`extremes=0,max_result_rows=100` |
- | `nullAsDefault` | `0` | `0` - 按原样处理 null 值,在向非 Nullable 列插入 null 时抛出异常;`1` - 按原样处理 null 值,并在插入时禁用 null 检查;`2` - 将 null 替换为相应数据类型的默认值(对查询和插入均生效) |
- | `jdbcCompliance` | `true` | 是否支持标准的同步 UPDATE/DELETE 操作以及伪事务 |
+ | `custom_http_params` | | 以逗号分隔的自定义 HTTP 查询参数,例如:`extremes=0,max_result_rows=100` |
+ | `nullAsDefault` | `0` | `0` - 按原样处理 null 值,在向非 Nullable 列插入 null 时抛出异常;`1` - 按原样处理 null 值,并在插入时禁用 null 检查机制;`2` - 将 null 替换为相应数据类型的默认值(对查询和插入均生效) |
+ | `jdbcCompliance` | `true` | 是否启用对标准同步 UPDATE/DELETE 操作和伪事务的支持 |
| `typeMappings` | | 自定义 ClickHouse 数据类型与 Java 类之间的映射关系,该配置会同时影响 [`getColumnType()`](https://docs.oracle.com/javase/8/docs/api/java/sql/ResultSetMetaData.html#getColumnType-int-) 和 [`getObject(Class<>?>`)](https://docs.oracle.com/javase/8/docs/api/java/sql/ResultSet.html#getObject-java.lang.String-java.lang.Class-) 的返回结果。例如:`UInt128=java.lang.String,UInt256=java.lang.String` |
| `wrapperObject` | `false` | [`getObject()`](https://docs.oracle.com/javase/8/docs/api/java/sql/ResultSet.html#getObject-int-) 是否应在处理 Array / Tuple 时返回 java.sql.Array / java.sql.Struct。 |
@@ -899,8 +932,8 @@ import TabItem from '@theme/TabItem';
:::note
* AggregatedFunction - :warning: 不支持通过 `SELECT * FROM table ...` 查询
- * Decimal - 在 21.9+ 中使用 `SET output_format_decimal_trailing_zeros=1` 以保持一致性
- * Enum - 既可以按字符串也可以按整数处理
+ * Decimal - 在 21.9 及更高版本中使用 `SET output_format_decimal_trailing_zeros=1` 以保持一致性
+ * Enum - 既可以作为字符串,也可以作为整数来处理
* UInt64 - 在 client-v1 中映射为 `long` 类型
:::
@@ -966,7 +999,7 @@ import TabItem from '@theme/TabItem';
}
```
- * [input 表函数文档](/sql-reference/table-functions/input/),并在可能的情况下优先使用该函数
+ * [input 表函数文档](/sql-reference/table-functions/input/),尽可能使用该函数
### 使用占位符插入数据 \{#insert-with-placeholders\}
@@ -1076,16 +1109,16 @@ import TabItem from '@theme/TabItem';
## SSL 属性 \{#ssl-properties\}
- | 名称 | 默认值 | 可选值 | 说明 |
- | -------------------- | ------ | ------------ | --------------------------------------- |
- | `ssl` | false | true, false | 是否为此连接启用 SSL/TLS |
- | `sslmode` | strict | strict, none | 是否校验 SSL/TLS 证书 |
- | `sslrootcert` | | | SSL/TLS 根证书文件路径 |
- | `sslcert` | | | SSL/TLS 证书文件路径 |
- | `sslkey` | | | PKCS#8 格式的 RSA 私钥 |
- | `key_store_type` | | JKS, PKCS12 | 指定 `KeyStore`/`TrustStore` 文件的类型或格式 |
- | `trust_store` | | | `TrustStore` 文件的路径 |
- | `key_store_password` | | | 用于访问 `KeyStore` 配置中指定的 `KeyStore` 文件的密码 |
+ | 名称 | 默认值 | 可选值 | 说明 |
+ | -------------------- | ------ | ------------ | -------------------------------------- |
+ | `ssl` | false | true, false | 是否为该连接启用 SSL/TLS 加密 |
+ | `sslmode` | strict | strict, none | 是否验证 SSL/TLS 证书 |
+ | `sslrootcert` | | | SSL/TLS 根证书的文件路径 |
+ | `sslcert` | | | SSL/TLS 证书的文件路径 |
+ | `sslkey` | | | PKCS#8 格式的 RSA 私钥 |
+ | `key_store_type` | | JKS, PKCS12 | 指定 `KeyStore`/`TrustStore` 文件的类型或格式 |
+ | `trust_store` | | | `TrustStore` 文件路径 |
+ | `key_store_password` | | | 用于访问 `KeyStore` 配置中指定 `KeyStore` 文件的密码 |
这些属性可确保您的 Java 应用程序通过加密连接与 ClickHouse 服务器进行通信,从而提高数据传输过程中的安全性。
@@ -1129,7 +1162,7 @@ import TabItem from '@theme/TabItem';
### Linux \{#v07-linux\}
- 在 Linux 上,仅配置等效设置可能无法解决问题。由于 Linux 处理套接字 keep-alive 设置的方式不同,需要执行额外的步骤。请按照以下步骤操作:
+ 在 Linux 上,仅配置等效设置可能无法解决问题。由于 Linux 处理套接字 keep-alive 设置的方式不同,需要执行额外的步骤。请按照以下步骤操作:
1. 在 `/etc/sysctl.conf` 或其他相关配置文件中调整以下 Linux 内核参数:
@@ -1140,9 +1173,9 @@ import TabItem from '@theme/TabItem';
* `net.inet.tcp.always_keepalive`: 1
* `net.ipv4.tcp_keepalive_intvl`: 75
* `net.ipv4.tcp_keepalive_probes`: 9
- * `net.ipv4.tcp_keepalive_time`: 60(可以考虑将该值从默认的 300 秒下调)
+ * `net.ipv4.tcp_keepalive_time`: 60(可以考虑将该值从默认的 300 秒降低)
- 2. 修改内核参数后,运行以下命令以使更改生效:
+ 2. 修改内核参数后,通过运行以下命令应用更改:
```shell
sudo sysctl -p
diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/integrations/misc/index.md b/i18n/zh/docusaurus-plugin-content-docs/current/integrations/misc/index.md
index d0a2ac3dd05..8f6a8f7f122 100644
--- a/i18n/zh/docusaurus-plugin-content-docs/current/integrations/misc/index.md
+++ b/i18n/zh/docusaurus-plugin-content-docs/current/integrations/misc/index.md
@@ -1,6 +1,6 @@
---
slug: /integrations/misc
-keywords: ['Retool', 'Easypanel', 'Splunk']
+keywords: ['可视化界面', 'GUI', '代理', '第三方集成']
title: '工具'
description: '“工具”部分的概览页'
doc_type: 'landing-page'
diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/integrations/tools/data-integration/pg_clickhouse/introduction.md b/i18n/zh/docusaurus-plugin-content-docs/current/integrations/tools/data-integration/pg_clickhouse/introduction.md
index a20717cc661..6496749b981 100644
--- a/i18n/zh/docusaurus-plugin-content-docs/current/integrations/tools/data-integration/pg_clickhouse/introduction.md
+++ b/i18n/zh/docusaurus-plugin-content-docs/current/integrations/tools/data-integration/pg_clickhouse/introduction.md
@@ -32,12 +32,10 @@ docker exec -it pg_clickhouse psql -U postgres -c 'CREATE EXTENSION pg_clickhous
## 测试用例:TPC-H \{#test-case-tpc-h\}
此表对比了在缩放因子为 1 时,[TPC-H] 查询在常规 PostgreSQL
-表与通过 pg_clickhouse 连接到 ClickHouse 的表之间的性能;✔︎ 表示完全下推,而短横线(-)表示在 1 分钟后取消该查询。
+表与通过 pg\_clickhouse 连接到 ClickHouse 的表之间的性能;✔︎ 表示完全下推,而短横线(-)表示在 1 分钟后取消该查询。
所有测试均在配备 36 GB 内存的 MacBook Pro M4 Max 上运行。
-{/* cd dev/tpch && make ch && make pg && make run */ }
-
-| 查询 | PostgreSQL | pg_clickhouse | 下推 |
+| 查询 | PostgreSQL | pg\_clickhouse | 下推 |
| ------: | ---------: | ----------------: | :-: |
| [查询 1] | 4693 ms | 268 ms | ✔︎ |
| [查询 2] | 458 ms | 3446 ms | |
@@ -49,7 +47,7 @@ docker exec -it pg_clickhouse psql -U postgres -c 'CREATE EXTENSION pg_clickhous
| [查询 8] | 342 ms | 156 ms | ✔︎ |
| [查询 9] | 3094 ms | 298 ms | ✔︎ |
| [查询 10] | 581 ms | 197 ms | ✔︎ |
-| [查询 11] | 212 ms | 24 ms | ✔︎ |
+| [查询 11] | 212 ms | 24 ms | |
| [查询 12] | 1116 ms | 84 ms | ✔︎ |
| [查询 13] | 958 ms | 1368 ms | |
| [查询 14] | 181 ms | 73 ms | ✔︎ |
@@ -62,7 +60,6 @@ docker exec -it pg_clickhouse psql -U postgres -c 'CREATE EXTENSION pg_clickhous
| [查询 21] | 1349 ms | 4434 ms | |
| [查询 22] | 258 ms | 1415 ms | |
-
### 从源代码编译 \{#compile-from-source\}
#### 通用 Unix \{#general-unix\}
diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/integrations/tools/data-integration/pg_clickhouse/reference.md b/i18n/zh/docusaurus-plugin-content-docs/current/integrations/tools/data-integration/pg_clickhouse/reference.md
index 5ae814a8b78..92e8f6ffb3a 100644
--- a/i18n/zh/docusaurus-plugin-content-docs/current/integrations/tools/data-integration/pg_clickhouse/reference.md
+++ b/i18n/zh/docusaurus-plugin-content-docs/current/integrations/tools/data-integration/pg_clickhouse/reference.md
@@ -334,7 +334,7 @@ DROP FOREIGN TABLE uact CASCADE;
## DML SQL 参考 \{#dml-sql-reference\}
-下面的 SQL [DML] 表达式可能会使用 pg_clickhouse。示例基于由 [make-logs.sql] 创建的这些 ClickHouse 表:
+下面的 SQL [DML] 表达式可能会使用 pg_clickhouse。示例基于这些 ClickHouse 表:
```sql
CREATE TABLE logs (
@@ -543,6 +543,14 @@ try=# EXECUTE avg_durations_between_dates('2025-12-09', '2025-12-13');
(5 rows)
```
+:::warning
+在 25.8 之前的 ClickHouse 版本中,参数化执行会导致 [http driver](#create-server)
+无法正确转换 DateTime 的时区;该[底层缺陷][underlying bug] 已在 25.8 中[修复][fixed]。
+请注意,有时即使不使用 `PREPARE`,PostgreSQL 也会使用参数化查询计划。
+对于任何需要精确时区转换但又无法升级到 25.8 或更高版本的查询,请改用
+[binary driver](#create-server)。
+:::
+
pg_clickhouse 像往常一样执行聚合下推,如在 [EXPLAIN](#explain) 的详细输出中所示:
```pgsql
@@ -635,7 +643,7 @@ LOAD
SET pg_clickhouse.session_settings = 'join_use_nulls 1, final 1';
```
-默认值为 `join_use_nulls 1`。将其设为空字符串以退回到 ClickHouse 服务器端的设置。
+默认值为 `join_use_nulls 1`。将其设为空字符串以回退到 ClickHouse 服务器的设置。
```sql
SET pg_clickhouse.session_settings = '';
@@ -674,7 +682,13 @@ SET pg_clickhouse.session_settings TO $$
$$;
```
-pg_clickhouse 不会验证这些设置,而是在每次查询时将它们传递给 ClickHouse。因此,它支持该 ClickHouse 版本的所有设置。
+在某些情况下,如果某些设置会干扰 pg_clickhouse 本身的运行,这些设置将被忽略。这些设置包括:
+
+* `date_time_output_format`:http 驱动程序要求其为 "iso"
+* `format_tsv_null_representation`:http 驱动程序要求使用默认值
+* `output_format_tsv_crlf_end_of_line`:http 驱动程序要求使用默认值
+
+除此之外,pg_clickhouse 不会验证这些设置,而是在每次查询时将它们传递给 ClickHouse。因此,它支持该 ClickHouse 版本的所有设置。
请注意,必须先加载 pg_clickhouse,然后才能设置
`pg_clickhouse.session_settings`;可以使用 [shared library preloading],或者
@@ -733,18 +747,16 @@ shared_preload_libraries = pg_clickhouse
对于每个会话而言,这有助于节省内存并降低加载开销,但在更新该库时需要重启集群。
-## 函数与运算符参考 \{#function-and-operator-reference\}
-
-### 数据类型 \{#data-types\}
+## 数据类型 \{#data-types\}
-pg_clickhouse 将以下 ClickHouse 数据类型映射到 PostgreSQL 数据类型:
+pg_clickhouse 将以下 ClickHouse 数据类型映射到 PostgreSQL 数据类型。[IMPORT FOREIGN SCHEMA](#import-foreign-schema) 在导入列时使用 PostgreSQL 列中的第一个数据类型;其他类型可以在 [CREATE FOREIGN TABLE](#create-foreign-table) 语句中使用:
| ClickHouse | PostgreSQL | 说明 |
-| -----------|------------------|--------------------------------------|
+|------------|------------------|--------------------------------------|
| Bool | boolean | |
| Date | date | |
| Date32 | date | |
-| DateTime | timestamp | |
+| DateTime | timestamptz | |
| Decimal | numeric | |
| Float32 | real | |
| Float64 | double precision | |
@@ -755,13 +767,129 @@ pg_clickhouse 将以下 ClickHouse 数据类型映射到 PostgreSQL 数据类型
| Int64 | bigint | |
| Int8 | smallint | |
| JSON | jsonb | 仅适用于 HTTP engine |
-| String | text | |
+| String | text, bytea | |
| UInt16 | integer | |
| UInt32 | bigint | |
| UInt64 | bigint | 当值大于 BIGINT 最大值时会报错 |
| UInt8 | smallint | |
| UUID | uuid | |
+后续部分将提供更多说明和详细信息。
+
+### BYTEA \{#bytea\}
+
+ClickHouse 不提供与 PostgreSQL [BYTEA] 类型等效的类型,但允许将任意字节存储在 [String] 类型中。通常,ClickHouse 字符串应映射到 PostgreSQL 的 [TEXT] 类型,但在处理二进制数据时,应将其映射到 [BYTEA]。示例:
+
+```sql
+-- Create clickHouse table with String columns.
+SELECT clickhouse_raw_query($$
+ CREATE TABLE bytes (
+ c1 Int8, c2 String, c3 String
+ ) ENGINE = MergeTree ORDER BY (c1);
+$$);
+
+-- Create foreign table with BYTEA columns.
+CREATE FOREIGN TABLE bytes (
+ c1 int,
+ c2 BYTEA,
+ c3 BYTEA
+) SERVER ch_srv OPTIONS( table_name 'bytes' );
+
+-- Insert binary data into the foreign table.
+INSERT INTO bytes
+SELECT n, sha224(bytea('val'||n)), decode(md5('int'||n), 'hex')
+ FROM generate_series(1, 4) n;
+
+-- View the results.
+SELECT * FROM bytes;
+```
+
+最终的 `SELECT` 查询将输出:
+
+```pgsql
+ c1 | c2 | c3
+----+------------------------------------------------------------+------------------------------------
+ 1 | \x1bf7f0cc821d31178616a55a8e0c52677735397cdde6f4153a9fd3d7 | \xae3b28cde02542f81acce8783245430d
+ 2 | \x5f6e9e12cd8592712e638016f4b1a2e73230ee40db498c0f0b1dc841 | \x23e7c6cacb8383f878ad093b0027d72b
+ 3 | \x53ac2c1fa83c8f64603fe9568d883331007d6281de330a4b5e728f9e | \x7e969132fc656148b97b6a2ee8bc83c1
+ 4 | \x4e3c2e4cb7542a45173a8dac939ddc4bc75202e342ebc769b0f5da2f | \x8ef30f44c65480d12b650ab6b2b04245
+(4 rows)
+```
+
+请注意,如果 ClickHouse 列中存在任何空字节(nul bytes),使用 [TEXT] 列的外部表将无法输出正确的值:
+
+```sql
+-- Create foreign table with TEXT columns.
+CREATE FOREIGN TABLE texts (
+ c1 int,
+ c2 TEXT,
+ c3 TEXT
+) SERVER ch_srv OPTIONS( table_name 'bytes' );
+
+-- Encode binary data as hex.
+SELECT c1, encode(c2::bytea, 'hex'), encode(c3::bytea, 'hex') FROM texts ORDER BY c1;
+```
+
+将输出:
+
+```pgsql
+ c1 | encode | encode
+----+----------------------------------------------------------+----------------------------------
+ 1 | 1bf7f0cc821d31178616a55a8e0c52677735397cdde6f4153a9fd3d7 | ae3b28cde02542f81acce8783245430d
+ 2 | 5f6e9e12cd8592712e638016f4b1a2e73230ee40db498c0f0b1dc841 | 23e7c6cacb8383f878ad093b
+ 3 | 53ac2c1fa83c8f64603fe9568d883331 | 7e969132fc656148b97b6a2ee8bc83c1
+ 4 | 4e3c2e4cb7542a45173a8dac939ddc4bc75202e342ebc769b0f5da2f | 8ef30f44c65480d12b650ab6b2b04245
+(4 rows)
+```
+
+请注意,第二行和第三行包含截断的值。这是因为 PostgreSQL 依赖以 nul 结尾的字符串,且不支持在字符串中包含 nul 字符。
+
+尝试将二进制值插入 [TEXT] 列将会成功并按预期工作:
+
+```sql
+-- Insert via text columns:
+TRUNCATE texts;
+INSERT INTO texts
+SELECT n, sha224(bytea('val'||n)), decode(md5('int'||n), 'hex')
+ FROM generate_series(1, 4) n;
+
+-- View the data.
+SELECT c1, encode(c2::bytea, 'hex'), encode(c3::bytea, 'hex') FROM texts ORDER BY c1;
+```
+
+文本列将正确显示:
+
+```pgdsql
+
+ c1 | encode | encode
+----+----------------------------------------------------------+----------------------------------
+ 1 | 1bf7f0cc821d31178616a55a8e0c52677735397cdde6f4153a9fd3d7 | ae3b28cde02542f81acce8783245430d
+ 2 | 5f6e9e12cd8592712e638016f4b1a2e73230ee40db498c0f0b1dc841 | 23e7c6cacb8383f878ad093b0027d72b
+ 3 | 53ac2c1fa83c8f64603fe9568d883331007d6281de330a4b5e728f9e | 7e969132fc656148b97b6a2ee8bc83c1
+ 4 | 4e3c2e4cb7542a45173a8dac939ddc4bc75202e342ebc769b0f5da2f | 8ef30f44c65480d12b650ab6b2b04245
+(4 rows)
+```
+
+但是如果将它们读取为 [BYTEA],则不会:
+
+```pgsql
+# SELECT * FROM bytes;
+ c1 | c2 | c3
+----+------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------
+ 1 | \x5c783162663766306363383231643331313738363136613535613865306335323637373733353339376364646536663431353361396664336437 | \x5c786165336232386364653032353432663831616363653837383332343534333064
+ 2 | \x5c783566366539653132636438353932373132653633383031366634623161326537333233306565343064623439386330663062316463383431 | \x5c783233653763366361636238333833663837386164303933623030323764373262
+ 3 | \x5c783533616332633166613833633866363436303366653935363864383833333331303037643632383164653333306134623565373238663965 | \x5c783765393639313332666336353631343862393762366132656538626338336331
+ 4 | \x5c783465336332653463623735343261343531373361386461633933396464633462633735323032653334326562633736396230663564613266 | \x5c783865663330663434633635343830643132623635306162366232623034323435
+(4 rows)
+```
+
+:::tip
+原则上,只将 [TEXT] 列用于编码字符串,将 [BYTEA] 列用于二进制数据,且不要在两者之间混用。
+:::
+
+
+## 函数与运算符参考 \{#function-and-operator-reference\}
+
### 函数 \{#functions\}
这些函数为对 ClickHouse 数据库进行查询提供接口。
@@ -839,6 +967,7 @@ SELECT clickhouse_raw_query(
* `btrim`: [trimBoth](https://clickhouse.com/docs/sql-reference/functions/string-functions#trimboth)
* `strpos`: [position](https://clickhouse.com/docs/sql-reference/functions/string-search-functions#position)
* `regexp_like`: [match](https://clickhouse.com/docs/sql-reference/functions/string-search-functions#match)
+* `md5`: [MD5](https://clickhouse.com/docs/sql-reference/functions/hash-functions#MD5)
### 自定义函数 \{#custom-functions\}
@@ -995,9 +1124,25 @@ Copyright (c) 2025-2026, ClickHouse
"PostgreSQL 文档:使用美元符号引用的字符串常量"
[library preloading]: https://www.postgresql.org/docs/18/runtime-config-client.html#RUNTIME-CONFIG-CLIENT-PRELOAD
+ "PostgreSQL 文档:共享库预加载"
-"PostgreSQL 文档:共享库预加载
- [PREPARE notes]: https://www.postgresql.org/docs/current/sql-prepare.html#SQL-PREPARE-NOTES
+[PREPARE notes]: https://www.postgresql.org/docs/current/sql-prepare.html#SQL-PREPARE-NOTES
"PostgreSQL 文档:PREPARE 注意事项"
- [query parameters]: https://clickhouse.com/docs/guides/developer/stored-procedures-and-prepared-statements#alternatives-to-prepared-statements-in-clickhouse
- "ClickHouse 文档:ClickHouse 中预处理语句的替代方案"
\ No newline at end of file
+
+[query parameters]: https://clickhouse.com/docs/guides/developer/stored-procedures-and-prepared-statements#alternatives-to-prepared-statements-in-clickhouse
+ "ClickHouse 文档:ClickHouse 中预处理语句的替代方案"
+
+[underlying bug]: https://github.com/ClickHouse/ClickHouse/issues/85847
+ "ClickHouse/ClickHouse#85847 某些 multipart 表单中的查询不会读取设置"
+
+[fixed]: https://github.com/ClickHouse/ClickHouse/pull/85570
+ "ClickHouse/ClickHouse#85570 修复使用 multipart 的 HTTP"
+
+[BYTEA]: https://www.postgresql.org/docs/current/datatype-binary.html
+ "PostgreSQL 文档:二进制数据类型"
+
+[String]: https://clickhouse.com/docs/sql-reference/data-types/string
+ "ClickHouse 文档:String"
+
+[TEXT]: https://www.postgresql.org/docs/current/datatype-character.html
+ "PostgreSQL 文档:字符类型"
\ No newline at end of file
diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/integrations/tools/data-integration/pg_clickhouse/tutorial.md b/i18n/zh/docusaurus-plugin-content-docs/current/integrations/tools/data-integration/pg_clickhouse/tutorial.md
index a13d119c11e..f60a6c75645 100644
--- a/i18n/zh/docusaurus-plugin-content-docs/current/integrations/tools/data-integration/pg_clickhouse/tutorial.md
+++ b/i18n/zh/docusaurus-plugin-content-docs/current/integrations/tools/data-integration/pg_clickhouse/tutorial.md
@@ -224,54 +224,54 @@ taxi=# \det+ taxi.*
```pgsql
taxi=# \d taxi.trips
- Foreign table "taxi.trips"
- Column | Type | Collation | Nullable | Default | FDW options
------------------------+-----------------------------+-----------+----------+---------+-------------
- trip_id | bigint | | not null | |
- vendor_id | text | | not null | |
- pickup_date | date | | not null | |
- pickup_datetime | timestamp without time zone | | not null | |
- dropoff_date | date | | not null | |
- dropoff_datetime | timestamp without time zone | | not null | |
- store_and_fwd_flag | smallint | | not null | |
- rate_code_id | smallint | | not null | |
- pickup_longitude | double precision | | not null | |
- pickup_latitude | double precision | | not null | |
- dropoff_longitude | double precision | | not null | |
- dropoff_latitude | double precision | | not null | |
- passenger_count | smallint | | not null | |
- trip_distance | double precision | | not null | |
- fare_amount | numeric(10,2) | | not null | |
- extra | numeric(10,2) | | not null | |
- mta_tax | numeric(10,2) | | not null | |
- tip_amount | numeric(10,2) | | not null | |
- tolls_amount | numeric(10,2) | | not null | |
- ehail_fee | numeric(10,2) | | not null | |
- improvement_surcharge | numeric(10,2) | | not null | |
- total_amount | numeric(10,2) | | not null | |
- payment_type | text | | not null | |
- trip_type | smallint | | not null | |
- pickup | character varying(25) | | not null | |
- dropoff | character varying(25) | | not null | |
- cab_type | text | | not null | |
- pickup_nyct2010_gid | smallint | | not null | |
- pickup_ctlabel | real | | not null | |
- pickup_borocode | smallint | | not null | |
- pickup_ct2010 | text | | not null | |
- pickup_boroct2010 | text | | not null | |
- pickup_cdeligibil | text | | not null | |
- pickup_ntacode | character varying(4) | | not null | |
- pickup_ntaname | text | | not null | |
- pickup_puma | integer | | not null | |
- dropoff_nyct2010_gid | smallint | | not null | |
- dropoff_ctlabel | real | | not null | |
- dropoff_borocode | smallint | | not null | |
- dropoff_ct2010 | text | | not null | |
- dropoff_boroct2010 | text | | not null | |
- dropoff_cdeligibil | text | | not null | |
- dropoff_ntacode | character varying(4) | | not null | |
- dropoff_ntaname | text | | not null | |
- dropoff_puma | integer | | not null | |
+ Foreign table "taxi.trips"
+ Column | Type | Collation | Nullable | Default | FDW options
+-----------------------+--------------------------+-----------+----------+---------+-------------
+ trip_id | bigint | | not null | |
+ vendor_id | text | | not null | |
+ pickup_date | date | | not null | |
+ pickup_datetime | timestamp with time zone | | not null | |
+ dropoff_date | date | | not null | |
+ dropoff_datetime | timestamp with time zone | | not null | |
+ store_and_fwd_flag | smallint | | not null | |
+ rate_code_id | smallint | | not null | |
+ pickup_longitude | double precision | | not null | |
+ pickup_latitude | double precision | | not null | |
+ dropoff_longitude | double precision | | not null | |
+ dropoff_latitude | double precision | | not null | |
+ passenger_count | smallint | | not null | |
+ trip_distance | double precision | | not null | |
+ fare_amount | numeric(10,2) | | not null | |
+ extra | numeric(10,2) | | not null | |
+ mta_tax | numeric(10,2) | | not null | |
+ tip_amount | numeric(10,2) | | not null | |
+ tolls_amount | numeric(10,2) | | not null | |
+ ehail_fee | numeric(10,2) | | not null | |
+ improvement_surcharge | numeric(10,2) | | not null | |
+ total_amount | numeric(10,2) | | not null | |
+ payment_type | text | | not null | |
+ trip_type | smallint | | not null | |
+ pickup | character varying(25) | | not null | |
+ dropoff | character varying(25) | | not null | |
+ cab_type | text | | not null | |
+ pickup_nyct2010_gid | smallint | | not null | |
+ pickup_ctlabel | real | | not null | |
+ pickup_borocode | smallint | | not null | |
+ pickup_ct2010 | text | | not null | |
+ pickup_boroct2010 | text | | not null | |
+ pickup_cdeligibil | text | | not null | |
+ pickup_ntacode | character varying(4) | | not null | |
+ pickup_ntaname | text | | not null | |
+ pickup_puma | integer | | not null | |
+ dropoff_nyct2010_gid | smallint | | not null | |
+ dropoff_ctlabel | real | | not null | |
+ dropoff_borocode | smallint | | not null | |
+ dropoff_ct2010 | text | | not null | |
+ dropoff_boroct2010 | text | | not null | |
+ dropoff_cdeligibil | text | | not null | |
+ dropoff_ntacode | character varying(4) | | not null | |
+ dropoff_ntaname | text | | not null | |
+ dropoff_puma | integer | | not null | |
Server: taxi_srv
FDW options: (database 'taxi', table_name 'trips', engine 'MergeTree')
```
@@ -372,7 +372,8 @@ FDW options: (database 'taxi', table_name 'trips', engine 'MergeTree')
Time: 30.978 ms
```
-* 计算每次行程的时长(分钟),然后按行程时长对结果进行分组:
+* 计算每次行程的时长(分钟),然后按
+ 行程时长对结果进行分组:
```pgsql
taxi=# SELECT
@@ -398,7 +399,7 @@ FDW options: (database 'taxi', table_name 'trips', engine 'MergeTree')
Time: 45.477 ms
```
-* 按一天中的各个小时,显示各街区的上车次数:
+* 按一天中的小时统计各街区的上车次数:
```pgsql
taxi=# SELECT
@@ -422,9 +423,11 @@ FDW options: (database 'taxi', table_name 'trips', engine 'MergeTree')
Time: 36.895 ms
```
-* 查询前往拉瓜迪亚或 JFK 机场的行程:
+* 将显示时区设置为纽约,并查询前往拉瓜迪亚或 JFK 机场的行程:
```pgsql
+ taxi=# SET timezone = 'America/New_York';
+ SET
taxi=# SELECT
pickup_datetime,
dropoff_datetime,
@@ -442,13 +445,13 @@ FDW options: (database 'taxi', table_name 'trips', engine 'MergeTree')
WHERE dropoff_nyct2010_gid IN (132, 138)
ORDER BY pickup_datetime
LIMIT 5;
- pickup_datetime | dropoff_datetime | total_amount | pickup_nyct2010_gid | dropoff_nyct2010_gid | airport_code | year | day | hour
- ---------------------+---------------------+--------------+---------------------+----------------------+--------------+------+-----+------
- 2015-07-01 00:04:14 | 2015-07-01 00:15:29 | 13.30 | -34 | 132 | JFK | 2015 | 1 | 0
- 2015-07-01 00:09:42 | 2015-07-01 00:12:55 | 6.80 | 50 | 138 | LGA | 2015 | 1 | 0
- 2015-07-01 00:23:04 | 2015-07-01 00:24:39 | 4.80 | -125 | 132 | JFK | 2015 | 1 | 0
- 2015-07-01 00:27:51 | 2015-07-01 00:39:02 | 14.72 | -101 | 138 | LGA | 2015 | 1 | 0
- 2015-07-01 00:32:03 | 2015-07-01 00:55:39 | 39.34 | 48 | 138 | LGA | 2015 | 1 | 0
+ pickup_datetime | dropoff_datetime | total_amount | pickup_nyct2010_gid | dropoff_nyct2010_gid | airport_code | year | day | hour
+ ------------------------+------------------------+--------------+---------------------+----------------------+--------------+------+-----+------
+ 2015-06-30 20:04:14-04 | 2015-06-30 20:15:29-04 | 13.30 | -34 | 132 | JFK | 2015 | 30 | 20
+ 2015-06-30 20:09:42-04 | 2015-06-30 20:12:55-04 | 6.80 | 50 | 138 | LGA | 2015 | 30 | 20
+ 2015-06-30 20:23:04-04 | 2015-06-30 20:24:39-04 | 4.80 | -125 | 132 | JFK | 2015 | 30 | 20
+ 2015-06-30 20:27:51-04 | 2015-06-30 20:39:02-04 | 14.72 | -101 | 138 | LGA | 2015 | 30 | 20
+ 2015-06-30 20:32:03-04 | 2015-06-30 20:55:39-04 | 39.34 | 48 | 138 | LGA | 2015 | 30 | 20
(5 rows)
Time: 17.450 ms
@@ -493,7 +496,7 @@ FDW options: (database 'taxi', table_name 'trips', engine 'MergeTree')
:::note
将 `LIFETIME` 设置为 0 会禁用自动更新,以避免对我们的 S3 存储桶产生不必要的流量。在其他情况下,你可能会进行不同的配置。有关详细信息,请参阅
[Refreshing dictionary data using
- LIFETIME](/sql-reference/dictionaries#refreshing-dictionary-data-using-lifetime)。
+ LIFETIME](/sql-reference/statements/create/dictionary/lifetime#refreshing-dictionary-data-using-lifetime)。
:::
2. 现在将其导入:
@@ -627,7 +630,7 @@ FDW options: (database 'taxi', table_name 'trips', engine 'MergeTree')
[EXPLAIN]: https://www.postgresql.org/docs/current/sql-explain.html
"SQL 命令:EXPLAIN"
-[dictionary]: /sql-reference/dictionaries/index.md
+[dictionary]: /sql-reference/statements/create/dictionary
[PGXN]: https://pgxn.org/dist/pg_clickhouse "PGXN 上的 pg_clickhouse"
@@ -640,5 +643,5 @@ FDW options: (database 'taxi', table_name 'trips', engine 'MergeTree')
[Postgres image]: https://hub.docker.com/_/postgres
"Docker Hub 上的 Postgres OCI 镜像"
-[Refreshing dictionary data using LIFETIME]: /sql-reference/dictionaries/index.md#refreshing-dictionary-data-using-lifetime
+[Refreshing dictionary data using LIFETIME]: /sql-reference/statements/create/dictionary/lifetime#refreshing-dictionary-data-using-lifetime
"ClickHouse 文档:使用 LIFETIME 刷新字典数据"
\ No newline at end of file
diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/integrations/tools/index.md b/i18n/zh/docusaurus-plugin-content-docs/current/integrations/tools/index.md
index d0be3b0e4aa..929f6b2b1e1 100644
--- a/i18n/zh/docusaurus-plugin-content-docs/current/integrations/tools/index.md
+++ b/i18n/zh/docusaurus-plugin-content-docs/current/integrations/tools/index.md
@@ -1,6 +1,6 @@
---
slug: /integrations/tools
-keywords: ['Retool', 'Easypanel', 'Splunk']
+keywords: ['ClickHouse integrations', 'SQL clients', 'data integrations', 'tools', 'third-party']
title: '工具'
description: '工具部分的概览页'
doc_type: 'landing-page'
@@ -12,4 +12,4 @@ doc_type: 'landing-page'
|-----------|---------------------------------------------------------------------------------------------------------------------------------|
| [SQL Client](/integrations/sql-clients) | 如何将 ClickHouse 与各种常见的数据库管理、分析和可视化工具集成 |
| [Data Integrations](/integrations/tools/data-integrations) | ClickHouse 的数据集成方案 |
-| [Misc](/integrations/audit-splunk) | ClickHouse 的其他工具 |
\ No newline at end of file
+| [Misc](/integrations/misc) | ClickHouse 的其他工具 |
\ No newline at end of file
diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/operations/caches.md b/i18n/zh/docusaurus-plugin-content-docs/current/operations/caches.md
index d4763cda39c..5a0c7565a35 100644
--- a/i18n/zh/docusaurus-plugin-content-docs/current/operations/caches.md
+++ b/i18n/zh/docusaurus-plugin-content-docs/current/operations/caches.md
@@ -27,10 +27,10 @@ doc_type: 'reference'
* [向量相似度索引](../engines/table-engines/mergetree-family/annindexes.md)缓存。
* [文本索引](../engines/table-engines/mergetree-family/textindexes.md#caching)缓存。
* [Avro 格式](/interfaces/formats/Avro) Schema 缓存。
-* [字典](../sql-reference/dictionaries/index.md)数据缓存。
+* [字典](../sql-reference/statements/create/dictionary/index.md)数据缓存。
* Schema 推断缓存。
* 基于 S3、Azure、本地以及其他磁盘的[文件系统缓存](storing-data.md)。
-* [用户态页缓存](/operations/userspace-page-cache)。
+* [用户态页缓存](/operations/userspace-page-cache)
* [查询缓存](query-cache.md)。
* [查询条件缓存](query-condition-cache.md)。
* 格式 Schema 缓存。
diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/operations/optimizing-performance/sampling-query-profiler.md b/i18n/zh/docusaurus-plugin-content-docs/current/operations/optimizing-performance/sampling-query-profiler.md
index cabf94bb8b1..0b180152eb0 100644
--- a/i18n/zh/docusaurus-plugin-content-docs/current/operations/optimizing-performance/sampling-query-profiler.md
+++ b/i18n/zh/docusaurus-plugin-content-docs/current/operations/optimizing-performance/sampling-query-profiler.md
@@ -52,7 +52,7 @@ SETTINGS allow_introspection_functions = 1
* 使用 `addressToLine`、`addressToLineWithInlines`、`addressToSymbol` 和 `demangle` 等[内省函数](../../sql-reference/functions/introspection.md),以获取 ClickHouse 代码中的函数名及其位置。要获取某条查询的分析信息,需要对 `trace_log` 表中的数据进行聚合。可以按单个函数或整条堆栈跟踪进行聚合。
-如果需要可视化 `trace_log` 信息,可尝试使用 [flamegraph](/interfaces/third-party/gui#clickhouse-flamegraph) 和 [speedscope](https://github.com/laplab/clickhouse-speedscope)。
+如果需要可视化 `trace_log` 信息,可尝试使用 [flamegraph](/interfaces/third-party/gui#clickhouse-flamegraph) 和 [speedscope](https://www.speedscope.app)。
## 示例 \{#example\}
diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/operations/server-configuration-parameters/_server_settings_outside_source.md b/i18n/zh/docusaurus-plugin-content-docs/current/operations/server-configuration-parameters/_server_settings_outside_source.md
index 078b5a2aef2..1a29f347a9a 100644
--- a/i18n/zh/docusaurus-plugin-content-docs/current/operations/server-configuration-parameters/_server_settings_outside_source.md
+++ b/i18n/zh/docusaurus-plugin-content-docs/current/operations/server-configuration-parameters/_server_settings_outside_source.md
@@ -375,7 +375,7 @@ ClickHouse 每隔 x 秒重新加载一次内置字典。这样就可以在不重
```
-## dictionaries_config \{#dictionaries_config\}
+## dictionaries_config \{#dictionaries_config\}
字典配置文件的路径。
@@ -386,7 +386,7 @@ ClickHouse 每隔 x 秒重新加载一次内置字典。这样就可以在不重
另请参阅:
-* "[Dictionaries](../../sql-reference/dictionaries/index.md)"。
+* "[Dictionaries](../../sql-reference/statements/create/dictionary/index.md)"。
**示例**
@@ -1901,12 +1901,14 @@ curl 127.0.0.1:9363/metrics
| `select_from_system_db_requires_grant` | 设置 `SELECT * FROM system.