расширение pg_azure_storage

Область применения: Azure Cosmos DB для PostgreSQL (на базе расширения базы данных Citus до PostgreSQL)

Расширение pg_azure_storage позволяет загружать данные в нескольких форматах файлов непосредственно из хранилища BLOB-объектов Azure в кластер Azure Cosmos DB для PostgreSQL. Включение расширения также разблокирует новые возможности команды COPY . Контейнеры с уровнем доступа "Private" или "BLOB-объект" требуют добавления закрытого ключа доступа.

Вы можете создать расширение, выполнив следующую команду:

SELECT create_extension('azure_storage');

azure_storage.account_add

Функция позволяет добавлять доступ к учетной записи хранения.

azure_storage.account_add
        (account_name_p text
        ,account_key_p text);

Аргументы

account_name_p

Учетная запись хранилища BLOB-объектов Azure (ABS) содержит все объекты ABS: большие двоичные объекты, файлы, очереди и таблицы. Учетная запись хранения предоставляет уникальное пространство имен для ABS, доступное из любой точки мира по протоколу HTTPS.

account_key_p

Ключи доступа к хранилищу BLOB-объектов Azure похожи на корневой пароль для учетной записи хранения. Не забудьте защитить ключи доступа. Для безопасного управления ключами и их замены воспользуйтесь Azure Key Vault. Ключ учетной записи хранится в таблице, доступной суперпользователем postgres, azure_storage_admin и всеми ролями, предоставленными этим разрешениям администратора. Чтобы узнать, какие учетные записи хранения существуют, используйте функцию account_list.

azure_storage.account_remove

Функция позволяет отменить доступ учетной записи к учетной записи хранения.

azure_storage.account_remove
        (account_name_p text);

Аргументы

account_name_p

Учетная запись хранилища BLOB-объектов Azure (ABS) содержит все объекты ABS: большие двоичные объекты, файлы, очереди и таблицы. Учетная запись хранения предоставляет уникальное пространство имен для ABS, доступное из любой точки мира по протоколу HTTPS.

azure_storage.account_user_add

Функция позволяет добавлять доступ к роли в учетную запись хранения.

azure_storage.account_user_add
        ( account_name_p text
        , user_p regrole);

Аргументы

account_name_p

Учетная запись хранилища BLOB-объектов Azure (ABS) содержит все объекты ABS: большие двоичные объекты, файлы, очереди и таблицы. Учетная запись хранения предоставляет уникальное пространство имен для ABS, доступное из любой точки мира по протоколу HTTPS.

user_p

Роль, созданная пользователем в кластере.

Примечание.

account_user_addaccount_remove,account_add,account_user_remove функции требуют разрешения на настройку для каждого отдельного узла в кластере.

azure_storage.account_user_remove

Функция позволяет удалять доступ к роли в учетную запись хранения.

azure_storage.account_user_remove
        (account_name_p text
        ,user_p regrole);

Аргументы

account_name_p

Учетная запись хранилища BLOB-объектов Azure (ABS) содержит все объекты ABS: большие двоичные объекты, файлы, очереди и таблицы. Учетная запись хранения предоставляет уникальное пространство имен для ABS, доступное из любой точки мира по протоколу HTTPS.

user_p

Роль, созданная пользователем в кластере.

azure_storage.account_list

Функция перечисляет учетную запись и роль с доступом к хранилищу BLOB-объектов Azure.

azure_storage.account_list
        (OUT account_name text
        ,OUT allowed_users regrole[]
        )
Returns TABLE;

Аргументы

account_name

Учетная запись хранилища BLOB-объектов Azure (ABS) содержит все объекты ABS: большие двоичные объекты, файлы, очереди и таблицы. Учетная запись хранения предоставляет уникальное пространство имен для ABS, доступное из любой точки мира по протоколу HTTPS.

allowed_users

Выводит список пользователей, имеющих доступ к хранилищу BLOB-объектов Azure.

Возвращаемый тип

TABLE

azure_storage.blob_list

Функция перечисляет доступные файлы BLOB-объектов в контейнере пользователя со своими свойствами.

azure_storage.blob_list
        (account_name text
        ,container_name text
        ,prefix text DEFAULT ''::text
        ,OUT path text
        ,OUT bytes bigint
        ,OUT last_modified timestamp with time zone
        ,OUT etag text
        ,OUT content_type text
        ,OUT content_encoding text
        ,OUT content_hash text
        )
Returns SETOF record;

Аргументы

account_name

Предоставляет storage account name уникальное пространство имен для данных хранилища Azure, доступных из любой точки мира по протоколу HTTPS.

container_name

Контейнер упорядочивает набор больших двоичных объектов, как каталог в файловой системе. Учетная запись хранения может содержать неограниченное количество контейнеров. В каждом контейнере может храниться неограниченное количество больших двоичных объектов. Имя контейнера должно быть допустимым DNS-именем, поскольку оно является частью уникального URI, используемого для адресации контейнера или его больших двоичных объектов. При присвоении имени контейнеру следуйте нижеприведенным правилам:

• Имена контейнеров могут содержать от 3 до 63 символов.
• Имена контейнеров должны начинаться с буквы или цифры и могут содержать только строчные буквы, цифры и тире (-).
• В именах контейнеров нельзя использовать два или более последовательных символа тире.

Универсальный код ресурса (URI) для контейнера аналогичен: https://myaccount.blob.core.windows.net/mycontainer

prefix

Возвращает файл из контейнера BLOB-объектов с соответствующими инициалами строки.

path

Полный путь к каталогу BLOB-объектов Azure.

байт

Размер объекта файла в байтах.

last_modified

После последнего изменения содержимого файла.

etag

Свойство ETag используется для оптимистического параллелизма во время обновлений. Это не метка времени, так как есть другое свойство с именем Timestamp, которое сохраняет последний раз, когда запись была обновлена. Например, если вы загружаете сущность и хотите обновить ее, ETag должна соответствовать тому, что сейчас хранится. Настройка соответствующего ETag важна, так как если у вас несколько пользователей редактировали один и тот же элемент, вы не хотите, чтобы они перезаписывали изменения друг друга.

content_type

Объект BLOB-объекта представляет большой двоичный объект, который представляет собой объект, подобный файлу неизменяемых необработанных данных. Их можно считывать как текстовые или двоичные данные или преобразовывать в readableStream, чтобы их методы можно было использовать для обработки данных. Большие двоичные объекты могут представлять данные, которые не обязательно в собственном формате JavaScript.

content_encoding

служба хранилища Azure позволяет определить свойство Content-Encoding в большом двоичном объекте. Для сжатого содержимого можно задать для свойства GZIP. Когда браузер обращается к содержимому, он автоматически распаковывает содержимое.

content_hash

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

Возвращаемый тип

Запись SETOF

Примечание.

Теперь разрешения можно перечислить контейнеры с уровнем доступа к частному и большому двоичному объекту для этого хранилища, но только в качестве citus userроли, предоставленной azure_storage_admin ей. Если вы создадите пользователя с именем support, по умолчанию доступ к содержимому контейнера не будет разрешен.

azure_storage.blob_get

Функция позволяет загружать содержимое файла \ файлов из контейнера с добавленной поддержкой фильтрации или обработки данных до импорта.

azure_storage.blob_get
        (account_name text
        ,container_name text
        ,path text
        ,decoder text DEFAULT 'auto'::text
        ,compression text DEFAULT 'auto'::text
        ,options jsonb DEFAULT NULL::jsonb
        )
RETURNS SETOF record;

Существует перегруженная версия функции, содержащая параметр rec, который позволяет удобно определять запись выходного формата.

azure_storage.blob_get
        (account_name text
        ,container_name text
        ,path text
        ,rec anyelement
        ,decoder text DEFAULT 'auto'::text
        ,compression text DEFAULT 'auto'::text
        ,options jsonb DEFAULT NULL::jsonb
        )
RETURNS SETOF anyelement;

Аргументы

организация

Учетная запись хранения предоставляет уникальное пространство имен для ваших служба хранилища Azure данных, доступных из любой точки мира по протоколу HTTPS.

контейнер

Контейнер упорядочивает набор больших двоичных объектов, как каталог в файловой системе. Учетная запись хранения может содержать неограниченное количество контейнеров. В каждом контейнере может храниться неограниченное количество больших двоичных объектов. Имя контейнера должно быть допустимым DNS-именем, поскольку оно является частью уникального URI, используемого для адресации контейнера или его больших двоичных объектов.

path

Имя BLOB-объекта, существующее в контейнере.

rec

Определите структуру выходных данных записи.

дешифратор

Укажите декодировщик формата BLOB-объектов для автоматического (по умолчанию) или любого из следующих значений.

Описание декодера

Формат	Description
csv	Формат разделенных запятыми значений, используемый PostgreSQL COPY
tsv	Значения, разделенные табуляции, формат копирования PostgreSQL по умолчанию
binary	Формат копирования двоичного postgreSQL
text	Файл, содержащий одно текстовое значение (например, большой json или XML)

compression

Определяет формат сжатия. Доступные варианты: autogzip >none. auto Использование параметра (по умолчанию) угадывает сжатие на основе расширения файла (.gz == gzip). none Параметр заставляет игнорировать расширение и не пытаться декодировать. Хотя gzip принудительно использует декодатор gzip (если у вас есть gzip-файл с нестандартным расширением). В настоящее время для расширения не поддерживаются другие форматы сжатия.

options

Для обработки пользовательских заголовков, настраиваемых разделителей, escape-символов и т. д. options работает аналогично COPY команде в PostgreSQL, параметр используется для blob_get функции.

Возвращаемый тип

SetOF Record / anyelement

Примечание.

Существует четыре служебные функции, называемые параметром в blob_get, которые помогают создавать значения для него. Каждая служебная функция предназначена для декодера, соответствующего его имени.

azure_storage.options_csv_get

Функция выступает в качестве служебной функции, называемой параметром в blob_get, что удобно для декодирования содержимого CSV.

azure_storage.options_csv_get
        (delimiter text DEFAULT NULL::text
        ,null_string text DEFAULT NULL::text
        ,header boolean DEFAULT NULL::boolean
        ,quote text DEFAULT NULL::text
        ,escape text DEFAULT NULL::text
        ,force_not_null text[] DEFAULT NULL::text[]
        ,force_null text[] DEFAULT NULL::text[]
        ,content_encoding text DEFAULT NULL::text
        )
Returns jsonb;

Аргументы

разделитель

Задает символ, разделяющий столбцы в каждой строке (строке) файла. По умолчанию используется символ табуляции в текстовом формате, запятая в формате CSV. Это должен быть один байтовый символ.

null_string

Указывает строку, представляющую значение NULL. Значение по умолчанию — \N (backslash-N) в текстовом формате и неквалированная пустая строка в формате CSV. Вы можете предпочесть пустую строку даже в текстовом формате, если вы не хотите различать значения NULL от пустых строк.

авторизации

Указывает, что файл содержит строку заголовка с именами каждого столбца в файле. В выходных данных первая строка содержит имена столбцов из таблицы.

quote

Указывает символ кавычек, используемый при кавычках значения данных. По умолчанию используется двойная кавычка. Это должен быть один байтовый символ.

escape

Указывает символ, который должен отображаться перед символом данных, соответствующим значению QUOTE. Значение по умолчанию совпадает со значением QUOTE (чтобы символ кавычки был двойным, если он отображается в данных). Это должен быть один байтовый символ.

force_not_null

Не сопоставляйте значения указанных столбцов со строкой NULL. В случае, если строка NULL пуста, это означает, что пустые значения считываются как строки нулевой длины, а не null, даже если они не кавычки.

force_null

Сопоставляет значения указанных столбцов со строкой NULL, даже если она была кавычек, и если совпадение установлено значение NULL. В случае, если строка NULL пуста, она преобразует в кавычки пустую строку в NULL.

content_encoding

Указывает, что файл закодирован в encoding_name. Если параметр опущен, используется текущая кодировка клиента.

Возвращаемый тип

jsonb

azure_storage.options_copy

Функция выступает в качестве служебной функции, называемой параметром в blob_get.

azure_storage.options_copy
        (delimiter text DEFAULT NULL::text
        ,null_string text DEFAULT NULL::text
        ,header boolean DEFAULT NULL::boolean
        ,quote text DEFAULT NULL::text
        ,escape text DEFAULT NULL::text
        ,force_quote text[] DEFAULT NULL::text[]
        ,force_not_null text[] DEFAULT NULL::text[]
        ,force_null text[] DEFAULT NULL::text[]
        ,content_encoding text DEFAULT NULL::text
        )
Returns jsonb;

Аргументы

разделитель

Задает символ, разделяющий столбцы в каждой строке (строке) файла. По умолчанию используется символ табуляции в текстовом формате, запятая в формате CSV. Это должен быть один байтовый символ.

null_string

Указывает строку, представляющую значение NULL. Значение по умолчанию — \N (backslash-N) в текстовом формате и неквалированная пустая строка в формате CSV. Вы можете предпочесть пустую строку даже в текстовом формате, если вы не хотите различать значения NULL от пустых строк.

авторизации

Указывает, что файл содержит строку заголовка с именами каждого столбца в файле. В выходных данных первая строка содержит имена столбцов из таблицы.

quote

Указывает символ кавычек, используемый при кавычках значения данных. По умолчанию используется двойная кавычка. Это должен быть один байтовый символ.

escape

Указывает символ, который должен отображаться перед символом данных, соответствующим значению QUOTE. Значение по умолчанию совпадает со значением QUOTE (чтобы символ кавычки был двойным, если он отображается в данных). Это должен быть один байтовый символ.

force_quote

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

force_not_null

Не сопоставляйте значения указанных столбцов со строкой NULL. В случае, если строка NULL пуста, это означает, что пустые значения считываются как строки нулевой длины, а не null, даже если они не кавычки.

force_null

Сопоставляет значения указанных столбцов со строкой NULL, даже если она была кавычек, и если совпадение установлено значение NULL. В случае, если строка NULL пуста, она преобразует в кавычки пустую строку в NULL.

content_encoding

Указывает, что файл закодирован в encoding_name. Если параметр опущен, используется текущая кодировка клиента.

Возвращаемый тип

jsonb

azure_storage.options_tsv

Функция выступает в качестве служебной функции, называемой параметром в blob_get. Это полезно для декодирования содержимого tsv.

azure_storage.options_tsv
        (delimiter text DEFAULT NULL::text
        ,null_string text DEFAULT NULL::text
        ,content_encoding text DEFAULT NULL::text
        )
Returns jsonb;

Аргументы

разделитель

Задает символ, разделяющий столбцы в каждой строке (строке) файла. По умолчанию используется символ табуляции в текстовом формате, запятая в формате CSV. Это должен быть один байтовый символ.

null_string

Указывает строку, представляющую значение NULL. Значение по умолчанию — \N (backslash-N) в текстовом формате и неквалированная пустая строка в формате CSV. Вы можете предпочесть пустую строку даже в текстовом формате, если вы не хотите различать значения NULL от пустых строк.

content_encoding

Указывает, что файл закодирован в encoding_name. Если параметр опущен, используется текущая кодировка клиента.

Возвращаемый тип

jsonb

azure_storage.options_binary

Функция выступает в качестве служебной функции, называемой параметром в blob_get. Это полезно для декодирования двоичного содержимого.

azure_storage.options_binary
        (content_encoding text DEFAULT NULL::text)
Returns jsonb;

Аргументы

content_encoding

Указывает, что файл закодирован в encoding_name. Если этот параметр не указан, используется текущая кодировка клиента.

Тип возвращаемых данных

jsonb

Примечание.

Теперь разрешения можно перечислить контейнеры с уровнем доступа к частному и большому двоичному объекту для этого хранилища, но только в качестве citus userроли, предоставленной azure_storage_admin ей. Если вы создаете новую поддержку с именем пользователя, доступ к содержимому контейнера по умолчанию не будет разрешен.

Примеры

В примерах используется пример учетной записи (pgquickstart) хранения Azure с пользовательскими файлами, отправленными для добавления в покрытие различных вариантов использования. Начнем с создания таблицы, используемой в наборе используемых примеров.

CREATE TABLE IF NOT EXISTS public.events
        (
         event_id bigint
        ,event_type text
        ,event_public boolean
        ,repo_id bigint
        ,payload jsonb
        ,repo jsonb
        ,user_id bigint
        ,org jsonb
        ,created_at timestamp without time zone
        );

Добавление ключа доступа учетной записи хранения (обязательно для уровня доступа = частный)

В примере показано добавление ключа доступа для учетной записи хранения для получения доступа к запросу из сеанса в кластере Azure Cosmos DB для Postgres.

SELECT azure_storage.account_add('pgquickstart', 'SECRET_ACCESS_KEY');

Совет

В учетной записи хранения откройте ключи доступа. Скопируйте имя учетной записи хранения и скопируйте ключ из раздела key1 (сначала нажмите кнопку "Показать рядом с ключом").

Удаление ключа доступа учетной записи хранения

В этом примере показано удаление ключа доступа для учетной записи хранения. Это действие приведет к удалению доступа к файлам, размещенным в частном контейнере в контейнере.

SELECT azure_storage.account_remove('pgquickstart');

Добавление доступа к роли в хранилище BLOB-объектов Azure

SELECT * FROM azure_storage.account_user_add('pgquickstart', 'support');

Вывод списка всех ролей с доступом к хранилищу BLOB-объектов Azure

SELECT * FROM azure_storage.account_list();

Удаление ролей с доступом к хранилищу BLOB-объектов Azure

SELECT * FROM azure_storage.account_user_remove('pgquickstart', 'support');

Вывод списка объектов в контейнере public

SELECT * FROM azure_storage.blob_list('pgquickstart','publiccontainer');

Вывод списка объектов в контейнере private

SELECT * FROM azure_storage.blob_list('pgquickstart','privatecontainer');

Примечание.

Добавление ключа доступа является обязательным.

Вывод списка объектов с определенными строковыми инициалами в общедоступном контейнере

SELECT * FROM azure_storage.blob_list('pgquickstart','publiccontainer','e');

Альтернативно

SELECT * FROM azure_storage.blob_list('pgquickstart','publiccontainer') WHERE path LIKE 'e%';

Чтение содержимого из объекта в контейнере

Функция blob_get извлекает файл из хранилища BLOB-объектов. Чтобы blob_get узнать, как проанализировать данные, которые можно передать (NULL::table_name), которое имеет тот же формат, что и файл.

SELECT * FROM azure_storage.blob_get
        ('pgquickstart'
        ,'publiccontainer'
        ,'events.csv.gz'
        , NULL::events)
LIMIT 5;

Кроме того, можно явно определить столбцы в предложении FROM .

SELECT * FROM azure_storage.blob_get('pgquickstart','publiccontainer','events.csv')
AS res (
         event_id BIGINT
        ,event_type TEXT
        ,event_public BOOLEAN
        ,repo_id BIGINT
        ,payload JSONB
        ,repo JSONB
        ,user_id BIGINT
        ,org JSONB
        ,created_at TIMESTAMP WITHOUT TIME ZONE)
LIMIT 5;

Использование параметра декодировщика

В примере показано использование decoder параметра. Обычно формат выводится из расширения файла, но если содержимое файла не имеет соответствующего расширения, можно передать аргумент декодера.

SELECT * FROM azure_storage.blob_get
        ('pgquickstart'
        ,'publiccontainer'
        ,'events'
        , NULL::events
        , decoder := 'csv')
LIMIT 5;

Использование сжатия с параметром декодатора

В примере показано, как применить сжатие gzip в сжатом файле gzip без стандартного расширения .gz.

SELECT * FROM azure_storage.blob_get
        ('pgquickstart'
        ,'publiccontainer'
        ,'events-compressed'
        , NULL::events
        , decoder := 'csv'
        , compression := 'gzip')
LIMIT 5;

Импорт отфильтрованного содержимого и изменение перед загрузкой из объекта формата CSV

В примере показана возможность фильтрации и изменения содержимого, импортируемого из объекта в контейнере перед загрузкой в таблицу SQL.

SELECT concat('P-',event_id::text) FROM azure_storage.blob_get
        ('pgquickstart'
        ,'publiccontainer'
        ,'events.csv'
        , NULL::events)
WHERE event_type='PushEvent'
LIMIT 5;

Запрос содержимого из файла с заголовками, настраиваемыми разделителями, escape-символами

Вы можете использовать пользовательские разделители и escape-символы, передав результат аргумента azure_storage.options_copy options .

SELECT * FROM azure_storage.blob_get
        ('pgquickstart'
        ,'publiccontainer'
        ,'events_pipe.csv'
        ,NULL::events
        ,options := azure_storage.options_csv_get(delimiter := '|' , header := 'true')
        );

Запрос агрегирования содержимого объекта в контейнере

Таким образом можно запрашивать данные без импорта.

SELECT event_type,COUNT(1) FROM azure_storage.blob_get
        ('pgquickstart'
        ,'publiccontainer'
        ,'events.csv'
        , NULL::events)
GROUP BY event_type
ORDER BY 2 DESC
LIMIT 5;

Следующие шаги

Использование Хранилище BLOB-объектов Azure с командой COPY

Прием данных с помощью pg_azure_storage