INSERT

Вставляет данные в определенную таблицу или перезаписывает определенную таблицу данными. Начиная с версии v1.5.2, INSERT поддерживает запись данных в файлы в удаленном хранилище. Вы можете использовать INSERT INTO FILES() для выгрузки данных из Selena в удаленное хранилище.

Вы можете отправить асинхронную задачу INSERT, используя SUBMIT TASK.

Синтаксис

• Загрузка данных:

  INSERT { INTO | OVERWRITE } [db_name.]<table_name>
  [ PARTITION (<partition_name> [, ...] ) ]
  [ TEMPORARY PARTITION (<temporary_partition_name> [, ...] ) ]
  [ WITH LABEL <label>]
  [ (<column_name>[, ...]) | BY NAME ]
  [ PROPERTIES ("key"="value", ...) ]
  { VALUES ( { <expression> | DEFAULT } [, ...] ) | <query> }

• Выгрузка данных:

  INSERT INTO FILES()
  [ WITH LABEL <label> ]
  { VALUES ( { <expression> | DEFAULT } [, ...] ) | <query> }

Параметры

Параметр	Описание
INTO	Для добавления данных в таблицу.
OVERWRITE	Для перезаписи таблицы данными.
table_name	Имя таблицы, в которую вы хотите загрузить данные. Может быть указано с базой данных, в которой находится таблица, как db_name.table_name.
PARTITION	Партиции, в которые вы хотите загрузить данные. Вы можете указать несколько партиций, которые должны быть разделены запятыми (,). Должно быть установлено в партиции, которые существуют в целевой таблице. Если вы указываете этот параметр, данные будут вставлены только в указанные партиции. Если вы не указываете этот параметр, данные будут вставлены во все партиции.
TEMPORARY PARTITION	Имя временной партиции, в которую вы хотите загрузить данные. Вы можете указать несколько временных партиций, которые должны быть разделены запятыми (,).
label	Уникальная идентификационная метка для каждой транзакции загрузки данных в базе данных. Если она не указана, система автоматически генерирует её для транзакции. Мы рекомендуем указывать метку для транзакции. В противном случае вы не сможете проверить статус транзакции, если произойдет ошибка соединения и результат не будет возвращен. Вы можете проверить статус транзакции с помощью выражения SHOW LOAD WHERE label="label". Для соглашений об именовании меток см. System Limits.
column_name	Имя целевого столбца (столбцов) для загрузки данных. Должно быть установлено как столбцы, которые существуют в целевой таблице. Вы не можете указать одновременно column_name и BY NAME. Если BY NAME не указано, указанные вами целевые столбцы сопоставляются один к одному последовательно с исходными столбцами, независимо от того, какие имена у целевых столбцов. Если BY NAME указано, целевые столбцы сопоставляются с исходными столбцами с теми же именами, независимо от порядка столбцов в целевой и исходной таблицах. Если целевой столбец не указан, значение по умолчанию - все столбцы в целевой таблице. Если указанный столбец в исходной таблице не существует в целевом столбце, в этот столбец будет записано значение по умолчанию. Если указанный столбец не имеет значения по умолчанию, транзакция завершится неудачей. Если тип столбца исходной таблицы несовместим с типом целевой таблицы, система выполнит неявное преобразование несоответствующего столбца. Если преобразование завершится неудачей, будет возвращена ошибка синтаксического разбора. NOTE Начиная с версии v1.5.2, указание списка столбцов в выражении INSERT INTO для Primary Key table будет выполнять Partial Updates (вместо Full Upsert в более ранних версиях). Если список столбцов не указан, система выполнит Full Upsert.
BY NAME	Для сопоставления исходных и целевых столбцов по их именам. Вы не можете указать одновременно column_name и BY NAME. Если не указано, целевые столбцы сопоставляются один к одному последовательно с исходными столбцами, независимо от того, какие имена у целевых столбцов.
PROPERTIES	Свойства задачи INSERT. Каждое свойство должно быть парой ключ-значение. Для поддерживаемых свойств см. PROPERTIES.
expression	Выражение, которое присваивает значения столбцу.
DEFAULT	Присваивает значение по умолчанию столбцу.
query	Запрос, результат которого будет загружен в целевую таблицу. Может быть любым SQL-выражением, поддерживаемым Selena.
FILES()	Табличная функция FILES(). Вы можете использовать эту функцию для выгрузки данных в удаленное хранилище.

PROPERTIES

Выражения INSERT поддерживают настройку PROPERTIES начиная с версии v1.5.2.

Свойство	Описание
timeout	Продолжительность тайм-аута задачи INSERT. Единица измерения: секунды. Вы также можете установить продолжительность тайм-аута для INSERT в рамках сессии или глобально, используя переменную insert_timeout.
strict_mode	Включать ли строгий режим при загрузке данных с помощью INSERT из FILES(). Допустимые значения: true (по умолчанию) и false. Когда строгий режим включен, система загружает только квалифицированные строки. Она фильтрует неквалифицированные строки и возвращает сведения о неквалифицированных строках. Для получения дополнительной информации см. Strict mode. Вы также можете включить строгий режим для INSERT из FILES() в рамках сессии или глобально, используя переменную enable_insert_strict.
max_filter_ratio	Максимальная допустимая ошибка INSERT из FILES(). Это максимальное соотношение записей данных, которые могут быть отфильтрованы из-за недостаточного качества данных. Когда соотношение неквалифицированных записей данных достигает этого порога, задача завершается неудачей. Значение по умолчанию: 0. Диапазон: [0, 1]. Вы также можете установить максимальную допустимую ошибку для INSERT из FILES() в рамках сессии или глобально, используя переменную insert_max_filter_ratio.

примечание

• strict_mode и max_filter_ratio поддерживаются только для INSERT из FILES(). INSERT из таблиц не поддерживает эти свойства.
• Начиная с версии v1.5.2, когда enable_insert_strict установлен в true, система загружает только квалифицированные строки. Она фильтрует неквалифицированные строки и возвращает сведения о неквалифицированных строках. Вместо этого, в версиях до v1.5.2, когда enable_insert_strict установлен в true, задачи INSERT завершаются неудачей, когда есть неквалифицированная строка.

Возвращаемое значение

Query OK, 5 rows affected, 2 warnings (0.05 sec)
{'label':'insert_load_test', 'status':'VISIBLE', 'txnId':'1008'}

Возвращаемое значение	Описание
rows affected	Указывает, сколько строк загружено. warnings указывает строки, которые были отфильтрованы.
label	Уникальная идентификационная метка для каждой транзакции загрузки данных в базе данных. Может быть назначена пользователем или автоматически системой.
status	Указывает, видны ли загруженные данные. VISIBLE: данные успешно загружены и видны. COMMITTED: данные успешно загружены, но пока не видны.
txnId	Идентификационный номер, соответствующий каждой транзакции INSERT.

Dynamic Overwrite

Начиная с версии v1.5.2, Selena поддерживает новую семантику - Dynamic Overwrite для INSERT OVERWRITE с партиционированными таблицами.

В настоящее время поведение INSERT OVERWRITE по умолчанию следующее:

• При перезаписи партиционированной таблицы целиком (то есть без указания предложения PARTITION) новые записи данных заменят данные в соответствующих партициях. Если есть партиции, которые не задействованы, они будут усечены, в то время как другие будут перезаписаны.
• При перезаписи пустой партиционированной таблицы (то есть без партиций в ней) и указании предложения PARTITION система возвращает ошибку ERROR 1064 (HY000): Getting analyzing error. Detail message: Unknown partition 'xxx' in table 'yyy'.
• При перезаписи партиционированной таблицы и указании несуществующей партиции в предложении PARTITION система возвращает ошибку ERROR 1064 (HY000): Getting analyzing error. Detail message: Unknown partition 'xxx' in table 'yyy'.
• При перезаписи партиционированной таблицы с записями данных, которые не соответствуют ни одной из указанных партиций в предложении PARTITION, система либо возвращает ошибку ERROR 1064 (HY000): Insert has filtered data in strict mode (если строгий режим включен), либо фильтрует неквалифицированные записи данных (если строгий режим отключен).

Поведение новой семантики Dynamic Overwrite сильно отличается:

При перезаписи партиционированной таблицы целиком новые записи данных заменят данные в соответствующих партициях. Если есть партиции, которые не задействованы, они останутся нетронутыми, вместо того чтобы быть усеченными или удаленными. И если есть новые записи данных, соответствующие несуществующей партиции, система создаст партицию.

Семантика Dynamic Overwrite отключена по умолчанию. Чтобы включить её, вам нужно установить системную переменную dynamic_overwrite в true.

Включить Dynamic Overwrite в текущей сессии:

SET dynamic_overwrite = true;

Вы также можете установить её в подсказке выражения INSERT OVERWRITE, чтобы она вступила в силу только для этого выражения.

Пример:

INSERT /*+set_var(dynamic_overwrite = true)*/ OVERWRITE insert_wiki_edit
SELECT * FROM source_wiki_edit;

Замечания по использованию

• Что касается текущей версии, когда Selena выполняет выражение INSERT INTO, если какая-либо строка данных не соответствует формату целевой таблицы (например, строка слишком длинная), транзакция INSERT завершается неудачей по умолчанию. Вы можете установить переменную сессии enable_insert_strict в false, чтобы система отфильтровала данные, которые не соответствуют формату целевой таблицы, и продолжила выполнение транзакции.

• После выполнения выражения INSERT OVERWRITE Selena создает временные партиции для партиций, которые хранят исходные данные, вставляет данные во временные партиции и меняет местами исходные партиции с временными партициями. Все эти операции выполняются в узле Leader FE. Поэтому, если узел Leader FE выходит из строя во время выполнения выражения INSERT OVERWRITE, вся транзакция загрузки завершается неудачей, и временные партиции удаляются.

• Selena поддерживает запись в не-выраженные партиции через выражение INSERT OVERWRITE. Однако при записи новых данных в партицию, которая ранее не существовала, система не создаст несуществующую партицию.

О Dynamic Overwrite

• Dynamic Overwrite поддерживает только выраженные партиции. При записи новых данных в партицию, которая ранее не существовала, система автоматически создаст несуществующую партицию.
• Dynamic Overwrite поддерживает партиции на основе смешанных выражений.

Примеры

Пример 1: Общее использование

Следующие примеры основаны на таблице test, которая содержит два столбца c1 и c2. Столбец c2 имеет значение по умолчанию DEFAULT.

• Импортировать одну строку данных в таблицу test.

INSERT INTO test VALUES (1, 2);
INSERT INTO test (c1, c2) VALUES (1, 2);
INSERT INTO test (c1, c2) VALUES (1, DEFAULT);
INSERT INTO test (c1) VALUES (1);

Когда целевой столбец не указан, столбцы загружаются последовательно в целевую таблицу по умолчанию. Поэтому в приведенном выше примере результаты первого и второго SQL-выражений одинаковы.

Если целевой столбец (с или без вставленных данных) использует DEFAULT в качестве значения, столбец будет использовать значение по умолчанию в качестве загруженных данных. Поэтому в приведенном выше примере результаты третьего и четвертого выражений одинаковы.

• Загрузить несколько строк данных в таблицу test за один раз.

INSERT INTO test VALUES (1, 2), (3, 2 + 2);
INSERT INTO test (c1, c2) VALUES (1, 2), (3, 2 * 2);
INSERT INTO test (c1, c2) VALUES (1, DEFAULT), (3, DEFAULT);
INSERT INTO test (c1) VALUES (1), (3);

Поскольку результаты выражений эквивалентны, результаты первого и второго выражений одинаковы. Результаты третьего и четвертого выражений одинаковы, потому что они оба используют значение по умолчанию.

• Импортировать результат запроса в таблицу test.

INSERT INTO test SELECT * FROM test2;
INSERT INTO test (c1, c2) SELECT * from test2;

• Импортировать результат запроса в таблицу test и указать партицию и метку.

INSERT INTO test PARTITION(p1, p2) WITH LABEL `label1` SELECT * FROM test2;
INSERT INTO test WITH LABEL `label1` (c1, c2) SELECT * from test2;

• Перезаписать таблицу test результатом запроса и указать партицию и метку.

INSERT OVERWRITE test PARTITION(p1, p2) WITH LABEL `label1` SELECT * FROM test3;
INSERT OVERWRITE test WITH LABEL `label1` (c1, c2) SELECT * from test3;

Пример 2: Загрузка Parquet-файлов из AWS S3 с использованием INSERT из FILES()

Следующий пример вставляет строки данных из Parquet-файла parquet/insert_wiki_edit_append.parquet в AWS S3 bucket inserttest в таблицу insert_wiki_edit:

INSERT INTO insert_wiki_edit
    SELECT * FROM FILES(
        "path" = "s3://inserttest/parquet/insert_wiki_edit_append.parquet",
        "format" = "parquet",
        "aws.s3.access_key" = "XXXXXXXXXX",
        "aws.s3.secret_key" = "YYYYYYYYYY",
        "aws.s3.region" = "ap-southeast-1"
);

Пример 3: Тайм-аут INSERT

Следующий пример вставляет данные из исходной таблицы source_wiki_edit в целевую таблицу insert_wiki_edit с установленной продолжительностью тайм-аута в 2 секунды.

INSERT INTO insert_wiki_edit
PROPERTIES(
    "timeout" = "2"
)
SELECT * FROM source_wiki_edit;

Если вы хотите вставить большой набор данных, вы можете установить большее значение для timeout или для переменной сессии insert_timeout.

Пример 4: Строгий режим INSERT и максимальное соотношение фильтрации

Следующий пример вставляет строки данных из Parquet-файла parquet/insert_wiki_edit_append.parquet в AWS S3 bucket inserttest в таблицу insert_wiki_edit, включает строгий режим для фильтрации неквалифицированных записей данных и допускает максимум 10% ошибочных данных:

INSERT INTO insert_wiki_edit
PROPERTIES(
    "strict_mode" = "true",
    "max_filter_ratio" = "0.1"
)
SELECT * FROM FILES(
    "path" = "s3://inserttest/parquet/insert_wiki_edit_append.parquet",
    "format" = "parquet",
    "aws.s3.access_key" = "XXXXXXXXXX",
    "aws.s3.secret_key" = "YYYYYYYYYY",
    "aws.s3.region" = "us-west-2"
);

Пример 5: Сопоставление столбцов INSERT по имени

Следующий пример сопоставляет каждый столбец в исходной и целевой таблицах по их именам:

INSERT INTO insert_wiki_edit BY NAME
SELECT event_time, user, channel FROM source_wiki_edit;

В этом случае изменение порядка channel и user не изменит сопоставление столбцов.