rozszerzenie pg_azure_storage
DOTYCZY: Usługa Azure Cosmos DB for PostgreSQL (obsługiwana przez rozszerzenie bazy danych Citus do bazy danych PostgreSQL)
Rozszerzenie pg_azure_storage umożliwia ładowanie danych w wielu formatach plików bezpośrednio z usługi Azure Blob Storage do klastra usługi Azure Cosmos DB for PostgreSQL. Włączenie rozszerzenia powoduje również odblokowanie nowych możliwości polecenia COPY . Kontenery z poziomem dostępu "Prywatny" lub "Obiekt blob" wymagają dodania klucza dostępu prywatnego.
Rozszerzenie można utworzyć, uruchamiając polecenie:
SELECT create_extension('azure_storage');
azure_storage.account_add
Funkcja umożliwia dodawanie dostępu do konta magazynu.
azure_storage.account_add
(account_name_p text
,account_key_p text);
Argumenty
account_name_p
Konto usługi Azure Blob Storage (ABS) zawiera wszystkie obiekty ABS: obiekty blob, pliki, kolejki i tabele. Konto magazynu zapewnia unikatową przestrzeń nazw dla abs, która jest dostępna z dowolnego miejsca na świecie za pośrednictwem protokołu HTTPS.
account_key_p
Klucze dostępu usługi Azure Blob Storage (ABS) są podobne do hasła głównego dla konta magazynu. Zawsze należy zachować ostrożność, aby chronić klucze dostępu. Usługa Azure Key Vault umożliwia bezpieczne zarządzanie kluczami i obracanie ich. Klucz konta jest przechowywany w tabeli, która jest dostępna przez administratora postgres, azure_storage_admin i wszystkie role przyznane te uprawnienia administratora. Aby sprawdzić, które konta magazynu istnieją, użyj account_list funkcji.
azure_storage.account_remove
Funkcja umożliwia odwołanie dostępu konta do konta magazynu.
azure_storage.account_remove
(account_name_p text);
Argumenty
account_name_p
Konto usługi Azure Blob Storage (ABS) zawiera wszystkie obiekty ABS: obiekty blob, pliki, kolejki i tabele. Konto magazynu zapewnia unikatową przestrzeń nazw dla abs, która jest dostępna z dowolnego miejsca na świecie za pośrednictwem protokołu HTTPS.
azure_storage.account_user_add
Funkcja umożliwia dodawanie dostępu do roli do konta magazynu.
azure_storage.account_user_add
( account_name_p text
, user_p regrole);
Argumenty
account_name_p
Konto usługi Azure Blob Storage (ABS) zawiera wszystkie obiekty ABS: obiekty blob, pliki, kolejki i tabele. Konto magazynu zapewnia unikatową przestrzeń nazw dla abs, która jest dostępna z dowolnego miejsca na świecie za pośrednictwem protokołu HTTPS.
user_p
Rola utworzona przez użytkownika widoczna w klastrze.
Uwaga
account_user_add
,account_add
,account_remove
,account_user_remove
funkcje wymagają ustawienia uprawnień dla poszczególnych węzłów w klastrze.
azure_storage.account_user_remove
Funkcja umożliwia usuwanie dostępu do roli na koncie magazynu.
azure_storage.account_user_remove
(account_name_p text
,user_p regrole);
Argumenty
account_name_p
Konto usługi Azure Blob Storage (ABS) zawiera wszystkie obiekty ABS: obiekty blob, pliki, kolejki i tabele. Konto magazynu zapewnia unikatową przestrzeń nazw dla abs, która jest dostępna z dowolnego miejsca na świecie za pośrednictwem protokołu HTTPS.
user_p
Rola utworzona przez użytkownika widoczna w klastrze.
azure_storage.account_list
Funkcja wyświetla listę kont i ról mających dostęp do usługi Azure Blob Storage.
azure_storage.account_list
(OUT account_name text
,OUT allowed_users regrole[]
)
Returns TABLE;
Argumenty
account_name
Konto usługi Azure Blob Storage (ABS) zawiera wszystkie obiekty ABS: obiekty blob, pliki, kolejki i tabele. Konto magazynu zapewnia unikatową przestrzeń nazw dla abs, która jest dostępna z dowolnego miejsca na świecie za pośrednictwem protokołu HTTPS.
allowed_users
Wyświetla listę użytkowników mających dostęp do usługi Azure Blob Storage.
Typ zwracany
TABELA
azure_storage.blob_list
Funkcja wyświetla listę dostępnych plików obiektów blob w kontenerze użytkownika z ich właściwościami.
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;
Argumenty
account_name
Element storage account name
udostępnia unikatową przestrzeń nazw dla danych usługi Azure Storage, które są dostępne z dowolnego miejsca na świecie za pośrednictwem protokołu HTTPS.
container_name
Kontener porządkuje zestaw obiektów blob, pełniąc funkcję podobną do katalogu w systemie plików. Konto magazynu może zawierać nieograniczoną liczbę kontenerów, a każdy kontener może zawierać nieograniczoną liczbę obiektów blob. Nazwa kontenera musi być prawidłową nazwą DNS, ponieważ stanowi część unikatowego identyfikatora URI używanego do adresowania kontenera lub jego obiektów blob. Postępuj zgodnie z tymi regułami podczas nazewnictwa kontenera:
- Nazwy kontenerów mogą mieć długość od 3 do 63 znaków.
- Nazwy kontenerów muszą zaczynać się literą lub cyfrą i mogą zawierać tylko małe litery, cyfry i znak kreski (-).
- Co najmniej dwa kolejne znaki kreski nie są dozwolone w nazwach kontenerów.
Identyfikator URI kontenera jest podobny do następującego: https://myaccount.blob.core.windows.net/mycontainer
przedrostek
Zwraca plik z kontenera obiektów blob z zgodnymi inicjałami ciągu.
path
Pełna kwalifikowana ścieżka katalogu obiektów blob platformy Azure.
B
Rozmiar obiektu pliku w bajtach.
last_modified
Kiedy zawartość pliku była ostatnio modyfikowana.
etag
Właściwość ETag jest używana do optymistycznej współbieżności podczas aktualizacji. Nie jest to sygnatura czasowa, ponieważ istnieje inna właściwość o nazwie Sygnatura czasowa, która przechowuje ostatni raz rekord został zaktualizowany. Jeśli na przykład załadujesz jednostkę i chcesz ją zaktualizować, element ETag musi być zgodny z tym, co jest obecnie przechowywane. Ustawienie odpowiedniego elementu ETag jest ważne, ponieważ jeśli masz wielu użytkowników edytując ten sam element, nie chcesz, aby zastępowały zmiany siebie nawzajem.
content_type
Obiekt blob reprezentuje obiekt blob, który jest obiektem przypominającym plik niezmiennych, nieprzetworzonych danych. Mogą być odczytywane jako dane tekstowe lub binarne albo konwertowane na element ReadableStream, dzięki czemu jego metody mogą być używane do przetwarzania danych. Obiekty blob mogą reprezentować dane, które nie muszą być w formacie natywnym języka JavaScript.
content_encoding
Usługa Azure Storage umożliwia zdefiniowanie właściwości Content-Encoding w obiekcie blob. W przypadku skompresowanej zawartości można ustawić właściwość na GZIP. Gdy przeglądarka uzyskuje dostęp do zawartości, automatycznie dekompresuje zawartość.
content_hash
Ten skrót służy do weryfikowania integralności obiektu blob podczas transportu. Po określeniu tego nagłówka usługa magazynu sprawdza skrót, który dotarł do wysłanego elementu. Jeśli dwa skróty nie są zgodne, operacja kończy się niepowodzeniem z kodem błędu 400 (Nieprawidłowe żądanie).
Typ zwracany
REKORD SETOF
Uwaga
Uprawnienia Teraz możesz wyświetlić listę kontenerów ustawionych na poziomy dostępu prywatny i blob dla tego magazynu, ale tylko jako citus user
, który ma przypisaną azure_storage_admin
mu rolę. Jeśli utworzysz nowego użytkownika o nazwie support
, domyślnie nie będzie on mógł uzyskiwać dostępu do zawartości kontenera.
azure_storage.blob_get
Funkcja umożliwia ładowanie zawartości plików \ plików z kontenera z dodatkową obsługą filtrowania lub manipulowania danymi przed zaimportowaniem.
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;
Istnieje przeciążona wersja funkcji zawierająca parametr rec, który umożliwia wygodne definiowanie rekordu formatu wyjściowego.
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;
Argumenty
account
Konto magazynu zapewnia unikatową przestrzeń nazw dla danych usługi Azure Storage, które są dostępne z dowolnego miejsca na świecie za pośrednictwem protokołu HTTPS.
kontener
Kontener porządkuje zestaw obiektów blob, pełniąc funkcję podobną do katalogu w systemie plików. Konto magazynu może zawierać nieograniczoną liczbę kontenerów, a każdy kontener może zawierać nieograniczoną liczbę obiektów blob. Nazwa kontenera musi być prawidłową nazwą DNS, ponieważ stanowi część unikatowego identyfikatora URI używanego do adresowania kontenera lub jego obiektów blob.
path
Nazwa obiektu blob istniejącego w kontenerze.
Rec
Zdefiniuj strukturę danych wyjściowych rekordu.
Dekoder
Określ dekoder formatu obiektów blob można ustawić na wartość automatyczną (domyślną) lub dowolną z następujących wartości
opis dekodera
Format | Opis |
---|---|
CSV | Format wartości rozdzielanych przecinkami używany przez kopię bazy danych PostgreSQL |
tsv | Wartości rozdzielane tabulatorami, domyślny format KOPIOWANIa postgreSQL |
dane binarne | Format kopiowania danych binarnych PostgreSQL |
text | Plik zawierający pojedynczą wartość tekstową (na przykład duży kod JSON lub XML) |
kompresja
Definiuje format kompresji. Dostępne opcje to auto
, gzip
i none
. Użycie auto
opcji (domyślnej) odgaduje kompresję na podstawie rozszerzenia pliku (.gz == gzip). Opcja none
wymusza ignorowanie rozszerzenia i nie próbuje dekodować. Podczas gdy gzip wymusza użycie dekodera gzip (dla gdy masz plik gzipped z rozszerzeniem niestandardowym). Obecnie nie obsługujemy żadnych innych formatów kompresji dla rozszerzenia.
options
W przypadku obsługi nagłówków niestandardowych, separatorów niestandardowych, znaków ucieczki itp. options
działa w podobny sposób do COPY
polecenia w usłudze PostgreSQL, parametr służy do blob_get funkcji.
Typ zwracany
SETOF Record/anyelement
Uwaga
Istnieją cztery funkcje narzędzi, nazywane jako parametr w blob_get, które ułatwiają tworzenie wartości dla niego. Każda funkcja narzędzia jest przeznaczona dla dekodera pasującego do jego nazwy.
azure_storage.options_csv_get
Funkcja działa jako funkcja narzędzia wywoływana jako parametr w blob_get, która jest przydatna do dekodowania zawartości 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;
Argumenty
Ogranicznik
Określa znak oddzielający kolumny w każdym wierszu (wierszu) pliku. Wartość domyślna to znak tabulacji w formacie tekstowym, przecinek w formacie CSV. Musi być pojedynczym znakiem jednobajtowym.
null_string
Określa ciąg reprezentujący wartość null. Wartość domyślna to \N (ukośnik odwrotny-N) w formacie tekstowym i pusty ciąg bez cudzysłów w formacie CSV. Możesz preferować pusty ciąg nawet w formacie tekstowym, jeśli nie chcesz odróżnić wartości null od pustych ciągów.
nagłówek
Określa, że plik zawiera wiersz nagłówka z nazwami każdej kolumny w pliku. W danych wyjściowych pierwszy wiersz zawiera nazwy kolumn z tabeli.
cytat
Określa znak cudzysłów, który ma być używany, gdy wartość danych jest cytowana. Wartość domyślna to podwójny cudzysłów. Musi być pojedynczym znakiem jednobajtowym.
escape
Określa znak, który powinien być wyświetlany przed znakiem danych zgodnym z wartością CUDZYSŁOWU. Wartość domyślna jest taka sama jak wartość CUDZYSŁOWU (tak aby znak cudzysłowu był podwajany, jeśli pojawia się w danych). Musi być pojedynczym znakiem jednobajtowym.
force_not_null
Nie dopasuj wartości określonych kolumn do ciągu o wartości null. W domyślnym przypadku, gdy ciąg null jest pusty, oznacza to, że puste wartości są odczytywane jako ciągi o zerowej długości, a nie wartości null, nawet jeśli nie są cytowane.
force_null
Dopasuj wartości określonych kolumn do ciągu o wartości null, nawet jeśli został zacytowany, a jeśli zostanie znalezione dopasowanie, ustaw wartość null. W domyślnym przypadku, w którym ciąg null jest pusty, konwertuje ciąg pusty cudzysłów na wartość NULL.
content_encoding
Określa, że plik jest zakodowany w encoding_name. Jeśli opcja zostanie pominięta, zostanie użyte bieżące kodowanie klienta.
Typ zwracany
jsonb
azure_storage.options_copy
Funkcja działa jako funkcja narzędzia wywoływana jako parametr w 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;
Argumenty
Ogranicznik
Określa znak oddzielający kolumny w każdym wierszu (wierszu) pliku. Wartość domyślna to znak tabulacji w formacie tekstowym, przecinek w formacie CSV. Musi być pojedynczym znakiem jednobajtowym.
null_string
Określa ciąg reprezentujący wartość null. Wartość domyślna to \N (ukośnik odwrotny-N) w formacie tekstowym i pusty ciąg bez cudzysłów w formacie CSV. Możesz preferować pusty ciąg nawet w formacie tekstowym, jeśli nie chcesz odróżnić wartości null od pustych ciągów.
nagłówek
Określa, że plik zawiera wiersz nagłówka z nazwami każdej kolumny w pliku. W danych wyjściowych pierwszy wiersz zawiera nazwy kolumn z tabeli.
cytat
Określa znak cudzysłów, który ma być używany, gdy wartość danych jest cytowana. Wartość domyślna to podwójny cudzysłów. Musi być pojedynczym znakiem jednobajtowym.
escape
Określa znak, który powinien być wyświetlany przed znakiem danych zgodnym z wartością CUDZYSŁOWU. Wartość domyślna jest taka sama jak wartość CUDZYSŁOWU (tak aby znak cudzysłowu był podwajany, jeśli pojawia się w danych). Musi być pojedynczym znakiem jednobajtowym.
force_quote
Wymusza cudzysłów, które mają być używane dla wszystkich wartości innych niż NULL w każdej określonej kolumnie. Dane wyjściowe null nigdy nie są cytowane. Jeśli wartość * jest określona, wartości inne niż NULL są cytowane we wszystkich kolumnach.
force_not_null
Nie dopasuj wartości określonych kolumn do ciągu o wartości null. W domyślnym przypadku, gdy ciąg null jest pusty, oznacza to, że puste wartości są odczytywane jako ciągi o zerowej długości, a nie wartości null, nawet jeśli nie są cytowane.
force_null
Dopasuj wartości określonych kolumn do ciągu o wartości null, nawet jeśli został zacytowany, a jeśli zostanie znalezione dopasowanie, ustaw wartość null. W domyślnym przypadku, w którym ciąg null jest pusty, konwertuje ciąg pusty cudzysłów na wartość NULL.
content_encoding
Określa, że plik jest zakodowany w encoding_name. Jeśli opcja zostanie pominięta, zostanie użyte bieżące kodowanie klienta.
Typ zwracany
jsonb
azure_storage.options_tsv
Funkcja działa jako funkcja narzędzia wywoływana jako parametr w blob_get. Jest to przydatne w przypadku dekodowania zawartości tsv.
azure_storage.options_tsv
(delimiter text DEFAULT NULL::text
,null_string text DEFAULT NULL::text
,content_encoding text DEFAULT NULL::text
)
Returns jsonb;
Argumenty
Ogranicznik
Określa znak oddzielający kolumny w każdym wierszu (wierszu) pliku. Wartość domyślna to znak tabulacji w formacie tekstowym, przecinek w formacie CSV. Musi być pojedynczym znakiem jednobajtowym.
null_string
Określa ciąg reprezentujący wartość null. Wartość domyślna to \N (ukośnik odwrotny-N) w formacie tekstowym i pusty ciąg bez cudzysłów w formacie CSV. Możesz preferować pusty ciąg nawet w formacie tekstowym, jeśli nie chcesz odróżnić wartości null od pustych ciągów.
content_encoding
Określa, że plik jest zakodowany w encoding_name. Jeśli opcja zostanie pominięta, zostanie użyte bieżące kodowanie klienta.
Typ zwracany
jsonb
azure_storage.options_binary
Funkcja działa jako funkcja narzędzia wywoływana jako parametr w blob_get. Jest to przydatne w przypadku dekodowania zawartości binarnej.
azure_storage.options_binary
(content_encoding text DEFAULT NULL::text)
Returns jsonb;
Argumenty
content_encoding
Określa, że plik jest zakodowany w encoding_name. Jeśli ta opcja zostanie pominięta, zostanie użyte bieżące kodowanie klienta.
Zwracany typ
jsonb
Uwaga
Uprawnienia Teraz możesz wyświetlić listę kontenerów ustawionych na poziomy dostępu prywatny i blob dla tego magazynu, ale tylko jako citus user
, który ma przypisaną azure_storage_admin
mu rolę. Jeśli utworzysz nowego użytkownika o nazwie support, dostęp do zawartości kontenera nie będzie domyślnie dozwolony.
Przykłady
W przykładach użyto przykładowego konta (pgquickstart)
usługi Azure Storage z plikami niestandardowymi przekazanymi do dodawania do różnych przypadków użycia. Możemy zacząć od utworzenia tabeli używanej w zestawie używanych przykładów.
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
);
Dodawanie klucza dostępu konta magazynu (obowiązkowe dla poziomu dostępu = prywatny)
W przykładzie pokazano dodawanie klucza dostępu dla konta magazynu w celu uzyskania dostępu do wykonywania zapytań z sesji w klastrze usługi Azure Cosmos DB for Postgres.
SELECT azure_storage.account_add('pgquickstart', 'SECRET_ACCESS_KEY');
Napiwek
Na koncie magazynu otwórz pozycję Klucze dostępu. Skopiuj nazwę konta magazynu i skopiuj sekcję Klucz z klucza key1 (musisz najpierw wybrać pozycję Pokaż obok klucza).
Usuwanie klucza dostępu konta magazynu
W przykładzie pokazano usuwanie klucza dostępu dla konta magazynu. Ta akcja spowoduje usunięcie dostępu do plików hostowanych w prywatnym zasobniku w kontenerze.
SELECT azure_storage.account_remove('pgquickstart');
Dodawanie dostępu do roli w usłudze Azure Blob Storage
SELECT * FROM azure_storage.account_user_add('pgquickstart', 'support');
Wyświetlanie listy wszystkich ról z dostępem do usługi Azure Blob Storage
SELECT * FROM azure_storage.account_list();
Usuwanie ról z dostępem do usługi Azure Blob Storage
SELECT * FROM azure_storage.account_user_remove('pgquickstart', 'support');
Wyświetlanie listy obiektów w kontenerze public
SELECT * FROM azure_storage.blob_list('pgquickstart','publiccontainer');
Wyświetlanie listy obiektów w kontenerze private
SELECT * FROM azure_storage.blob_list('pgquickstart','privatecontainer');
Uwaga
Dodawanie klucza dostępu jest obowiązkowe.
Wyświetlanie listy obiektów z określonymi inicjałami ciągu w kontenerze publicznym
SELECT * FROM azure_storage.blob_list('pgquickstart','publiccontainer','e');
Ewentualnie
SELECT * FROM azure_storage.blob_list('pgquickstart','publiccontainer') WHERE path LIKE 'e%';
Odczytywanie zawartości z obiektu w kontenerze
Funkcja blob_get
pobiera plik z magazynu obiektów blob. Aby blob_get wiedzieć, jak analizować dane, możesz przekazać wartość (NULL::table_name), która ma taki sam format jak plik.
SELECT * FROM azure_storage.blob_get
('pgquickstart'
,'publiccontainer'
,'events.csv.gz'
, NULL::events)
LIMIT 5;
Alternatywnie możemy jawnie zdefiniować kolumny w klauzuli 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;
Użyj opcji dekodera
W przykładzie pokazano użycie decoder
opcji. Zwykle format jest wnioskowany z rozszerzenia pliku, ale gdy zawartość pliku nie ma pasującego rozszerzenia, można przekazać argument dekodera.
SELECT * FROM azure_storage.blob_get
('pgquickstart'
,'publiccontainer'
,'events'
, NULL::events
, decoder := 'csv')
LIMIT 5;
Użyj kompresji z opcją dekodera
W przykładzie pokazano, jak wymusić użycie kompresji gzip w skompresowanym pliku gzip bez standardowego rozszerzenia .gz.
SELECT * FROM azure_storage.blob_get
('pgquickstart'
,'publiccontainer'
,'events-compressed'
, NULL::events
, decoder := 'csv'
, compression := 'gzip')
LIMIT 5;
Zaimportuj przefiltrowaną zawartość i zmodyfikuj ją przed załadowaniem z obiektu formatu csv
W przykładzie pokazano możliwość filtrowania i modyfikowania zawartości importowanej z obiektu w kontenerze przed załadowaniem jej do tabeli SQL.
SELECT concat('P-',event_id::text) FROM azure_storage.blob_get
('pgquickstart'
,'publiccontainer'
,'events.csv'
, NULL::events)
WHERE event_type='PushEvent'
LIMIT 5;
Wykonywanie zapytań o zawartość z pliku z nagłówkami, separatorami niestandardowymi, znakami ucieczki
Separatory niestandardowe i znaki ucieczki można użyć, przekazując wynik azure_storage.options_copy
do argumentu options
.
SELECT * FROM azure_storage.blob_get
('pgquickstart'
,'publiccontainer'
,'events_pipe.csv'
,NULL::events
,options := azure_storage.options_csv_get(delimiter := '|' , header := 'true')
);
Zapytanie agregacji dotyczące zawartości obiektu w kontenerze
W ten sposób można wykonywać zapytania dotyczące danych bez importowania ich.
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;