pg_azure_storage tillägg

GÄLLER FÖR: Azure Cosmos DB for PostgreSQL (drivs av Citus-databastillägget till PostgreSQL)

Med tillägget pg_azure_storage kan du läsa in data i flera filformat direkt från Azure Blob Storage till ditt Azure Cosmos DB for PostgreSQL-kluster. Om du aktiverar tillägget låss även nya funktioner i COPY-kommandot upp. Containrar med åtkomstnivån "Privat" eller "Blob" kräver att du lägger till en privat åtkomstnyckel.

Du kan skapa tillägget genom att köra:

SELECT create_extension('azure_storage');

azure_storage.account_add

Med funktionen kan du lägga till åtkomst till ett lagringskonto.

azure_storage.account_add
        (account_name_p text
        ,account_key_p text);

Argument

account_name_p

Ett Azure Blob Storage-konto (ABS) innehåller alla dina ABS-objekt: blobbar, filer, köer och tabeller. Lagringskontot tillhandahåller ett unikt namnområde för din ABS som är tillgänglig var som helst i världen via HTTPS.

account_key_p

Åtkomstnycklarna för Azure Blob Storage (ABS) liknar ett rotlösenord för ditt lagringskonto. Var alltid noga med att skydda dina åtkomstnycklar. Använd Azure Key Vault för att hantera och rotera dina nycklar på ett säkert sätt. Kontonyckeln lagras i en tabell som är tillgänglig för postgres-superanvändaren, azure_storage_admin och alla roller som beviljats dessa administratörsbehörigheter. Om du vill se vilka lagringskonton som finns använder du funktionen account_list.

azure_storage.account_remove

Funktionen tillåter återkallande av kontoåtkomst till lagringskonto.

azure_storage.account_remove
        (account_name_p text);

Argument

account_name_p

Azure Blob Storage-kontot (ABS) innehåller alla dina ABS-objekt: blobar, filer, köer och tabeller. Lagringskontot tillhandahåller ett unikt namnområde för din ABS som är tillgänglig var som helst i världen via HTTPS.

azure_storage.account_user_add

Funktionen gör det möjligt att lägga till åtkomst för en roll till ett lagringskonto.

azure_storage.account_user_add
        ( account_name_p text
        , user_p regrole);

Argument

account_name_p

Ett Azure Blob Storage-konto (ABS) innehåller alla dina ABS-objekt: blobbar, filer, köer och tabeller. Lagringskontot tillhandahåller ett unikt namnområde för din ABS som är tillgänglig var som helst i världen via HTTPS.

user_p

Rollen som skapats av användaren visas i klustret.

Kommentar

account_user_addaccount_removeaccount_user_remove Funktioneraccount_add kräver inställningsbehörigheter för varje enskild nod i klustret.

azure_storage.account_user_remove

Funktionen gör det möjligt att ta bort åtkomst för en roll till ett lagringskonto.

azure_storage.account_user_remove
        (account_name_p text
        ,user_p regrole);

Argument

account_name_p

Ett Azure Blob Storage-konto (ABS) innehåller alla dina ABS-objekt: blobbar, filer, köer och tabeller. Lagringskontot tillhandahåller ett unikt namnområde för din ABS som är tillgänglig var som helst i världen via HTTPS.

user_p

Rollen som skapats av användaren visas i klustret.

azure_storage.account_list

Funktionen visar den konto- och roll som har åtkomst till Azure Blob Storage.

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

Argument

account_name

Azure Blob Storage-kontot (ABS) innehåller alla dina ABS-objekt: blobar, filer, köer och tabeller. Lagringskontot tillhandahåller ett unikt namnområde för din ABS som är tillgänglig var som helst i världen via HTTPS.

allowed_users

Visar en lista över användare som har åtkomst till Azure Blob Storage.

Returtyp

TABELL

azure_storage.blob_list

Funktionen visar de tillgängliga blobfilerna i en användarcontainer med deras egenskaper.

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;

Argument

account_name

Tillhandahåller storage account name ett unikt namnområde för dina Azure Storage-data som är tillgängliga var som helst i världen via HTTPS.

container_name

I en container finns en uppsättning med blobbar, ungefär som i en katalog i ett filsystem. Ett lagringskonto kan omfatta ett obegränsat antal containrar, och varje container kan lagra ett obegränsat antal blobar. Ett containernamn måste vara ett giltigt DNS-namn eftersom det utgör en del av den unika URI som används för att adressera containern eller dess blobar. Följ dessa regler när du namnger en container:

• Containernamn kan vara mellan 3 och 63 tecken långa.
• Containernamn måste börja med en bokstav eller siffra och får endast innehålla gemener, siffror och bindestreck (-).
• Två eller flera på varandra följande bindestreckstecken tillåts inte i containernamn.

URI:n för en container liknar: https://myaccount.blob.core.windows.net/mycontainer

prefix

Returnerar filen från blobcontainern med matchande sträng initialer.

path

Fullständig kvalificerad sökväg för Azure Blob Directory.

byte

Filobjektets storlek i byte.

last_modified

När ändrades filinnehållet senast.

etag

En ETag-egenskap används för optimistisk samtidighet under uppdateringar. Det är inte en tidsstämpel eftersom det finns en annan egenskap som heter Tidsstämpel som lagrar den senaste gången en post uppdaterades. Om du till exempel läser in en entitet och vill uppdatera den måste ETag matcha det som för närvarande lagras. Det är viktigt att ange lämplig ETag eftersom du inte vill att flera användare ska skriva över varandras ändringar om du har flera användare som redigerar samma objekt.

content_type

Blob-objektet representerar en blob, som är ett filliknande objekt med oföränderliga rådata. De kan läsas som text eller binära data eller konverteras till en ReadableStream så att dess metoder kan användas för bearbetning av data. Blobar kan representera data som inte nödvändigtvis är i ett JavaScript-inbyggt format.

content_encoding

Med Azure Storage kan du definiera egenskapen Content-Encoding på en blob. För komprimerat innehåll kan du ange egenskapen till GZIP. När webbläsaren kommer åt innehållet dekomprimerar den automatiskt innehållet.

content_hash

Den här hashen används för att verifiera blobens integritet under transporten. När det här huvudet har angetts kontrollerar lagringstjänsten den hash som har anlänt med den som skickades. Om de två hashvärdena inte matchar misslyckas åtgärden med felkoden 400 (felaktig begäran).

Returtyp

SETOF-post

Kommentar

Behörigheter Nu kan du visa en lista över containrar som är inställda på åtkomstnivåer för privat och blobb för lagringen, men bara som , citus usersom har rollen azure_storage_admin beviljad till den. Om du skapar en ny användare med namnet supportfår den inte åtkomst till containerinnehållet som standard.

azure_storage.blob_get

Funktionen tillåter inläsning av innehållet i filen \ filer inifrån containern, med extra stöd för filtrering eller manipulering av data före import.

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;

Det finns en överbelastad funktionsversion som innehåller rec-parametern som gör att du enkelt kan definiera utdataformatposten.

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;

Argument

konto

Lagringskontot tillhandahåller ett unikt namnområde för dina Azure Storage-data som är tillgängliga var som helst i världen via HTTPS.

container

I en container finns en uppsättning med blobbar, ungefär som i en katalog i ett filsystem. Ett lagringskonto kan omfatta ett obegränsat antal containrar, och varje container kan lagra ett obegränsat antal blobar. Ett containernamn måste vara ett giltigt DNS-namn eftersom det utgör en del av den unika URI som används för att adressera containern eller dess blobar.

path

Blobnamn som finns i containern.

Rec

Definiera utdatastrukturen för posten.

avkodare

Ange blobformatet Decoder kan ställas in på auto (standard) eller något av följande värden

beskrivning av avkodare

Format	Beskrivning
csv	Format för kommaavgränsade värden som används av PostgreSQL COPY
tsv	Tabbavgränsade värden, standardformatet PostgreSQL COPY
binary	Binärt PostgreSQL COPY-format
text	En fil som innehåller ett enda textvärde (till exempel stor JSON eller XML)

komprimering

Definierar komprimeringsformatet. Tillgängliga alternativ är auto, gzip & none. Användningen av auto alternativet (standard) gissar komprimering baserat på filnamnstillägget (.gz == gzip). Alternativet none tvingar att ignorera tillägget och inte försöka avkoda. Medan gzip tvingar med hjälp av gzip-avkodaren (för när du har en gzipped-fil med ett tillägg som inte är standard). Vi stöder för närvarande inte några andra komprimeringsformat för tillägget.

alternativ

För hantering av anpassade huvuden, anpassade avgränsare, escape-tecken osv. options fungerar på liknande sätt som COPY kommandot i PostgreSQL använder parametern för att blob_get funktion.

Returtyp

SETOF-post/anyelement

Kommentar

Det finns fyra verktygsfunktioner som kallas för en parameter i blob_get som hjälper dig att skapa värden för den. Varje verktygsfunktion är avsedd för avkodaren som matchar dess namn.

azure_storage.options_csv_get

Funktionen fungerar som en verktygsfunktion som kallas för en parameter i blob_get, vilket är användbart för avkodning av csv-innehållet.

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;

Argument

avgränsare

Anger det tecken som avgränsar kolumner inom varje rad (rad) i filen. Standardvärdet är ett fliktecken i textformat, ett kommatecken i CSV-format. Det måste vara ett enda enbytestecken.

null_string

Anger strängen som representerar ett null-värde. Standardvärdet är \N (backslash-N) i textformat och en ociterad tom sträng i CSV-format. Du kanske föredrar en tom sträng även i textformat för fall där du inte vill skilja null-värden från tomma strängar.

sidhuvud

Anger att filen innehåller en rubrikrad med namnen på varje kolumn i filen. Vid utdata innehåller den första raden kolumnnamnen från tabellen.

citera

Anger det citattecken som ska användas när ett datavärde citeras. Standardvärdet är dubbelcitat. Det måste vara ett enda enbytestecken.

ESC

Anger det tecken som ska visas före ett datatecken som matchar OFFERT-värdet. Standardvärdet är detsamma som OFFERT-värdet (så att citattecknet fördubblas om det visas i data). Det måste vara ett enda enbytestecken.

force_not_null

Matcha inte de angivna kolumnernas värden mot nullsträngen. I standardfallet där nullsträngen är tom innebär det att tomma värden läse som nolllängdssträngar i stället för null, även om de inte citeras.

force_null

Matcha de angivna kolumnernas värden mot null-strängen, även om den har citerats, och om en matchning hittas anger du värdet till NULL. I standardfallet där null-strängen är tom konverteras en citerad tom sträng till NULL.

content_encoding

Anger att filen är kodad i encoding_name. Om alternativet utelämnas används den aktuella klientkodningen.

Returtyp

jsonb

azure_storage.options_copy

Funktionen fungerar som en verktygsfunktion som kallas för en parameter i 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;

Argument

avgränsare

Anger det tecken som avgränsar kolumner inom varje rad (rad) i filen. Standardvärdet är ett fliktecken i textformat, ett kommatecken i CSV-format. Det måste vara ett enda enbytestecken.

null_string

Anger strängen som representerar ett null-värde. Standardvärdet är \N (backslash-N) i textformat och en ociterad tom sträng i CSV-format. Du kanske föredrar en tom sträng även i textformat för fall där du inte vill skilja null-värden från tomma strängar.

sidhuvud

Anger att filen innehåller en rubrikrad med namnen på varje kolumn i filen. Vid utdata innehåller den första raden kolumnnamnen från tabellen.

citera

Anger det citattecken som ska användas när ett datavärde citeras. Standardvärdet är dubbelcitat. Det måste vara ett enda enbytestecken.

ESC

Anger det tecken som ska visas före ett datatecken som matchar OFFERT-värdet. Standardvärdet är detsamma som OFFERT-värdet (så att citattecknet fördubblas om det visas i data). Det måste vara ett enda enbytestecken.

force_quote

Tvingar citattecken att användas för alla icke-NULL-värden i varje angiven kolumn. NULL-utdata citeras aldrig. Om * anges anges icke-NULL-värden i alla kolumner.

force_not_null

Matcha inte de angivna kolumnernas värden mot nullsträngen. I standardfallet där nullsträngen är tom innebär det att tomma värden läse som nolllängdssträngar i stället för null, även om de inte citeras.

force_null

Matcha de angivna kolumnernas värden mot null-strängen, även om den har citerats, och om en matchning hittas anger du värdet till NULL. I standardfallet där null-strängen är tom konverteras en citerad tom sträng till NULL.

content_encoding

Anger att filen är kodad i encoding_name. Om alternativet utelämnas används den aktuella klientkodningen.

Returtyp

jsonb

azure_storage.options_tsv

Funktionen fungerar som en verktygsfunktion som kallas för en parameter i blob_get. Det är användbart för att avkoda tsv-innehållet.

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

Argument

avgränsare

Anger det tecken som avgränsar kolumner inom varje rad (rad) i filen. Standardvärdet är ett fliktecken i textformat, ett kommatecken i CSV-format. Det måste vara ett enda enbytestecken.

null_string

Anger strängen som representerar ett null-värde. Standardvärdet är \N (backslash-N) i textformat och en ociterad tom sträng i CSV-format. Du kanske föredrar en tom sträng även i textformat för fall där du inte vill skilja null-värden från tomma strängar.

content_encoding

Anger att filen är kodad i encoding_name. Om alternativet utelämnas används den aktuella klientkodningen.

Returtyp

jsonb

azure_storage.options_binary

Funktionen fungerar som en verktygsfunktion som kallas för en parameter i blob_get. Det är användbart för avkodning av binärt innehåll.

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

Argument

content_encoding

Anger att filen är kodad i encoding_name. Om det här alternativet utelämnas används den aktuella klientkodningen.

Returtyp

jsonb

Kommentar

Behörigheter Nu kan du visa en lista över containrar som är inställda på åtkomstnivåer för privat och blobb för lagringen, men bara som , citus usersom har rollen azure_storage_admin beviljad till den. Om du skapar en ny användare med namnet support får den inte åtkomst till containerinnehåll som standard.

Exempel

De exempel som används använder azure-exempellagringskonto (pgquickstart) med anpassade filer som laddats upp för att lägga till täckning för olika användningsfall. Vi kan börja med att skapa en tabell som används i den uppsättning exempel som används.

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
        );

Lägga till åtkomstnyckel för lagringskonto (obligatoriskt för åtkomstnivå = privat)

Exemplet visar hur du lägger till åtkomstnyckeln för lagringskontot för att få åtkomst till frågor från en session i Azure Cosmos DB for Postgres-klustret.

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

Dricks

Öppna Åtkomstnycklar i ditt lagringskonto. Kopiera lagringskontots namn och kopiera avsnittet Nyckel från key1 (du måste välja Visa bredvid nyckeln först).

Ta bort åtkomstnyckeln för lagringskontot

Exemplet visar hur du tar bort åtkomstnyckeln för ett lagringskonto. Den här åtgärden skulle leda till att åtkomsten till filer som finns i en privat bucket tas bort i containern.

SELECT azure_storage.account_remove('pgquickstart');

Lägga till åtkomst för en roll i Azure Blob Storage

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

Visa en lista över alla roller med åtkomst i Azure Blob Storage

SELECT * FROM azure_storage.account_list();

Ta bort roller med åtkomst på Azure Blob Storage

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

Visa en lista över objekten i en public container

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

Visa en lista över objekten i en private container

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

Kommentar

Det är obligatoriskt att lägga till åtkomstnyckeln.

Visa en lista över objekt med specifika stränginitieringar i en offentlig container

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

Alternativt

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

Läsa innehåll från ett objekt i en container

Funktionen blob_get hämtar en fil från Blob Storage. För att blob_get ska veta hur du parsar data kan du antingen skicka ett värde (NULL::table_name), som har samma format som filen.

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

Alternativt kan vi uttryckligen definiera kolumnerna FROM i -satsen.

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;

Använda avkodningsalternativ

Exemplet illustrerar användningen av decoder alternativet. Normalt härleds formatet från filnamnstillägget, men när filinnehållet inte har något matchande tillägg kan du skicka avkodarargumentet.

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

Använda komprimering med avkodningsalternativet

Exemplet visar hur du framtvingar användning av gzip-komprimering på en gzip-komprimerad fil utan ett standardnamnstillägg för .gz.

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

Importera filtrerat innehåll och ändra innan det läses in från csv-formatobjekt

Exemplet illustrerar möjligheten att filtrera och ändra innehållet som importeras från objektet i containern innan det läses in i en SQL-tabell.

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

Fråga efter innehåll från en fil med rubriker, anpassade avgränsare, escape-tecken

Du kan använda anpassade avgränsare och escape-tecken genom att skicka resultatet till azure_storage.options_copy options argumentet.

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

Sammansättningsfråga om innehållet i ett objekt i containern

På så sätt kan du köra frågor mot data utan att importera dem.

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;

Nästa steg

Så här använder du Azure Blob Storage med kommandot COPY

Så här matar du in data med hjälp av pg_azure_storage