pg_azure_storage-extensie
VAN TOEPASSING OP: 
Azure Cosmos DB for PostgreSQL (mogelijk gemaakt door de Citus-database-extensie naar PostgreSQL)
Met de pg_azure_storage-extensie kunt u gegevens in meerdere bestandsindelingen rechtstreeks vanuit Azure Blob Storage laden naar uw Azure Cosmos DB for PostgreSQL-cluster. Als u de extensie inschakelt, worden ook nieuwe mogelijkheden van de opdracht COPY ontgrendeld. Voor containers met toegangsniveau Privé of Blob moet persoonlijke toegangssleutel worden toegevoegd.
U kunt de extensie maken door het volgende uit te voeren:
SELECT create_extension('azure_storage');
azure_storage.account_add
Met de functie kunt u toegang tot een opslagaccount toevoegen.
azure_storage.account_add
(account_name_p text
,account_key_p text);
Argumenten
account_name_p
Een Azure Blob Storage-account (ABS) bevat al uw ABS-objecten: blobs, bestanden, wachtrijen en tabellen. Het opslagaccount biedt een unieke naamruimte voor uw ABS die overal ter wereld toegankelijk is via HTTPS.
account_key_p
Uw toegangssleutels voor Azure Blob Storage (ABS) zijn vergelijkbaar met een hoofdwachtwoord voor uw opslagaccount. Wees altijd voorzichtig met het beveiligen van uw toegangssleutels. Gebruik Azure Key Vault om uw sleutels veilig te beheren en te roteren. De accountsleutel wordt opgeslagen in een tabel die toegankelijk is voor de postgres-superuser, azure_storage_admin en alle rollen waaraan deze beheerdersmachtigingen zijn verleend. Gebruik de functie account_list om te zien welke opslagaccounts er bestaan.
azure_storage.account_remove
Met de functie kan accounttoegang tot het opslagaccount worden ingeroepen.
azure_storage.account_remove
(account_name_p text);
Argumenten
account_name_p
Het Azure Blob Storage-account (ABS) bevat al uw ABS-objecten: blobs, bestanden, wachtrijen en tabellen. Het opslagaccount biedt een unieke naamruimte voor uw ABS die overal ter wereld toegankelijk is via HTTPS.
azure_storage.account_user_add
Met de functie kunt u toegang voor een rol toevoegen aan een opslagaccount.
azure_storage.account_user_add
( account_name_p text
, user_p regrole);
Argumenten
account_name_p
Een Azure Blob Storage-account (ABS) bevat al uw ABS-objecten: blobs, bestanden, wachtrijen en tabellen. Het opslagaccount biedt een unieke naamruimte voor uw ABS die overal ter wereld toegankelijk is via HTTPS.
user_p
Rol die is gemaakt door de gebruiker die zichtbaar is in het cluster.
Notitie
account_user_add,account_add,account_remove,account_user_remove functies vereisen het instellen van machtigingen voor elke afzonderlijke knooppunten in het cluster.
azure_storage.account_user_remove
Met de functie kunt u de toegang voor een rol naar een opslagaccount verwijderen.
azure_storage.account_user_remove
(account_name_p text
,user_p regrole);
Argumenten
account_name_p
Een Azure Blob Storage-account (ABS) bevat al uw ABS-objecten: blobs, bestanden, wachtrijen en tabellen. Het opslagaccount biedt een unieke naamruimte voor uw ABS die overal ter wereld toegankelijk is via HTTPS.
user_p
Rol die is gemaakt door de gebruiker die zichtbaar is in het cluster.
azure_storage.account_list
De functie geeft een lijst weer van het account en de rol die toegang heeft tot Azure Blob Storage.
azure_storage.account_list
(OUT account_name text
,OUT allowed_users regrole[]
)
Returns TABLE;
Argumenten
account_name
Het Azure Blob Storage-account (ABS) bevat al uw ABS-objecten: blobs, bestanden, wachtrijen en tabellen. Het opslagaccount biedt een unieke naamruimte voor uw ABS die overal ter wereld toegankelijk is via HTTPS.
allowed_users
Geeft een lijst weer van de gebruikers die toegang hebben tot de Azure Blob-opslag.
Retourtype
TABEL
azure_storage.blob_list
De functie bevat de beschikbare blobbestanden in een gebruikerscontainer met hun eigenschappen.
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;
Argumenten
account_name
Het storage account name biedt een unieke naamruimte voor uw Azure-opslaggegevens die overal ter wereld toegankelijk zijn via HTTPS.
container_name
Een container kan een of meer blobs bevatten, net zoals een map een of meer bestanden kan bevatten in een bestandssysteem. Een opslagaccount kan een onbeperkt aantal containers bevatten en een container kan een onbeperkt aantal blobs bevatten. Een containernaam moet een geldige DNS-naam zijn, omdat deze deel uitmaakt van de unieke URI die wordt gebruikt om de container of de bijbehorende blobs te adresseren. Volg deze regels bij het benoemen van een container:
- Containernamen kunnen tussen 3 en 63 tekens lang zijn.
- Containernamen moeten beginnen met een letter of cijfer en mogen alleen kleine letters, cijfers en het streepje (-) bevatten.
- Twee of meer opeenvolgende streepjes zijn niet toegestaan in containernamen.
De URI voor een container is vergelijkbaar met: https://myaccount.blob.core.windows.net/mycontainer
voorvoegsel
Retourneert een bestand uit de blobcontainer met overeenkomende initialen van tekenreeksen.
path
Volledig gekwalificeerde pad van Azure Blob-map.
bytes
De grootte van het bestandsobject in bytes.
last_modified
Wanneer is de bestandsinhoud voor het laatst gewijzigd.
etag
Een ETag-eigenschap wordt gebruikt voor optimistische gelijktijdigheid tijdens updates. Het is geen tijdstempel omdat er een andere eigenschap is met de naam Timestamp waarin de laatste keer dat een record is bijgewerkt, wordt opgeslagen. Als u bijvoorbeeld een entiteit laadt en deze wilt bijwerken, moet de ETag overeenkomen met wat momenteel is opgeslagen. Het instellen van de juiste ETag is belangrijk omdat als u meerdere gebruikers hetzelfde item bewerkt, u niet wilt dat ze elkaars wijzigingen overschrijven.
content_type
Het Blob-object vertegenwoordigt een blob, een bestandachtig object met onveranderbare, onbewerkte gegevens. Ze kunnen worden gelezen als tekst of binaire gegevens, of worden geconverteerd naar een ReadableStream, zodat de methoden kunnen worden gebruikt voor het verwerken van de gegevens. Blobs kunnen gegevens vertegenwoordigen die niet noodzakelijkerwijs in een systeemeigen JavaScript-indeling zijn.
content_encoding
Met Azure Storage kunt u de eigenschap Content-Encoding definiëren op een blob. Voor gecomprimeerde inhoud kunt u de eigenschap instellen op GZIP. Wanneer de browser toegang heeft tot de inhoud, wordt de inhoud automatisch gedecomprimeert.
content_hash
Deze hash wordt gebruikt om de integriteit van de blob tijdens het transport te controleren. Wanneer deze header is opgegeven, controleert de opslagservice de hash die is aangekomen met de hash die is verzonden. Als de twee hashes niet overeenkomen, mislukt de bewerking met foutcode 400 (Ongeldige aanvraag).
Retourtype
SETOF-record
Notitie
Met machtigingen kunt u nu containers weergeven die zijn ingesteld op toegangsniveaus voor privé- en blobtoegang voor die opslag, maar alleen als de citus user, waaraan de azure_storage_admin rol is verleend. Als u een nieuwe gebruiker met de naam supportmaakt, is het niet standaard toegestaan om toegang te krijgen tot de inhoud van de container.
azure_storage.blob_get
Met de functie kan de inhoud van bestand \ bestanden vanuit de container worden geladen, met toegevoegde ondersteuning voor het filteren of bewerken van gegevens, voorafgaand aan het importeren.
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;
Er is een overbelaste versie van de functie, die rec-parameter bevat waarmee u de uitvoerindelingrecord gemakkelijk kunt definiëren.
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;
Argumenten
Account
Het opslagaccount biedt een unieke naamruimte voor uw Azure Storage-gegevens die overal ter wereld toegankelijk zijn via HTTPS.
container
Een container kan een of meer blobs bevatten, net zoals een map een of meer bestanden kan bevatten in een bestandssysteem. Een opslagaccount kan een onbeperkt aantal containers bevatten en een container kan een onbeperkt aantal blobs bevatten. Een containernaam moet een geldige DNS-naam zijn, omdat deze deel uitmaakt van de unieke URI die wordt gebruikt om de container of de bijbehorende blobs te adresseren.
path
De blobnaam die aanwezig is in de container.
Rec
Definieer de recorduitvoerstructuur.
Decoder
De decoder voor blob-indeling opgeven kan worden ingesteld op automatisch (standaard) of een van de volgende waarden
decoderbeschrijving
| Notatie | Beschrijving |
|---|---|
| CSV | Door komma's gescheiden waardenindeling die wordt gebruikt door PostgreSQL COPY |
| tsv | Door tabs gescheiden waarden, de standaard PostgreSQL COPY-indeling |
| binair | Binaire PostgreSQL COPY-indeling |
| sms verzenden | Een bestand met één tekstwaarde (bijvoorbeeld grote JSON of XML) |
compressie
Hiermee definieert u de compressie-indeling. Beschikbare opties zijn auto, gzip & none. Het gebruik van de auto optie (standaard), raadt de compressie op basis van de bestandsextensie (.gz == gzip). De optie none dwingt de extensie te negeren en probeert de extensie niet te decoderen. Gzip dwingt het gebruik van de gzip-decoder af (voor wanneer u een gegzipped-bestand met een niet-standaardextensie hebt). Momenteel bieden we geen ondersteuning voor andere compressie-indelingen voor de extensie.
Opties
Voor het verwerken van aangepaste headers, aangepaste scheidingstekens, escapetekens, enzovoort, options werkt op dezelfde manier als COPY de opdracht in PostgreSQL, wordt de parameter gebruikt voor blob_get functie.
Retourtype
SETOF-record/anyelement
Notitie
Er zijn vier hulpprogrammafuncties die worden aangeroepen als een parameter binnen blob_get die helpen bij het bouwen van waarden. Elke functie van het hulpprogramma wordt aangewezen voor de decoder die overeenkomt met de naam.
azure_storage.options_csv_get
De functie fungeert als een hulpprogrammafunctie die wordt aangeroepen als een parameter binnen blob_get, wat handig is voor het decoderen van de CSV-inhoud.
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;
Argumenten
scheidingsteken
Hiermee geeft u het teken op dat kolommen in elke rij (regel) van het bestand scheidt. De standaardwaarde is een tabteken in tekstindeling, een komma in CSV-indeling. Het moet één byteteken zijn.
null_string
Hiermee geeft u de tekenreeks die een null-waarde vertegenwoordigt. De standaardwaarde is \N (backslash-N) in tekstindeling en een niet-aanhalingstekenloze lege tekenreeks in CSV-indeling. Mogelijk geeft u de voorkeur aan een lege tekenreeks, zelfs in tekstindeling voor gevallen waarin u null-waarden niet wilt onderscheiden van lege tekenreeksen.
koptekst
Hiermee geeft u op dat het bestand een koptekstregel bevat met de namen van elke kolom in het bestand. In de uitvoer bevat de eerste regel de kolomnamen uit de tabel.
citaat
Hiermee geeft u het aanhalingsteken op dat moet worden gebruikt wanneer een gegevenswaarde wordt aanhalingstekens. De standaardwaarde is dubbele aanhalingstekens. Het moet één byteteken zijn.
escape
Hiermee geeft u het teken op dat moet worden weergegeven vóór een gegevensteken dat overeenkomt met de prijsopgavewaarde. De standaardwaarde is hetzelfde als de prijsopgavewaarde (zodat het aanhalingsteken wordt verdubbeld als het in de gegevens wordt weergegeven). Het moet één byteteken zijn.
force_not_null
Komt niet overeen met de waarden van de opgegeven kolommen ten opzichte van de null-tekenreeks. In het standaardscenario waarin de null-tekenreeks leeg is, betekent dit dat lege waarden worden gelezen als tekenreeksen met de lengte nul in plaats van nullen, zelfs wanneer ze niet worden geciteerd.
force_null
Koppel de waarden van de opgegeven kolommen aan de null-tekenreeks, zelfs als deze is geciteerd en als er een overeenkomst wordt gevonden, stelt u de waarde in op NULL. In het standaardscenario waarin de null-tekenreeks leeg is, wordt een lege tekenreeks tussen aanhalingstekens omgezet in NULL.
content_encoding
Hiermee geeft u op dat het bestand is gecodeerd in de encoding_name. Als de optie wordt weggelaten, wordt de huidige clientcodering gebruikt.
Retourtype
jsonb
azure_storage.options_copy
De functie fungeert als een hulpprogrammafunctie die wordt aangeroepen als een parameter binnen 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;
Argumenten
scheidingsteken
Hiermee geeft u het teken op dat kolommen in elke rij (regel) van het bestand scheidt. De standaardwaarde is een tabteken in tekstindeling, een komma in CSV-indeling. Het moet één byteteken zijn.
null_string
Hiermee geeft u de tekenreeks die een null-waarde vertegenwoordigt. De standaardwaarde is \N (backslash-N) in tekstindeling en een niet-aanhalingstekenloze lege tekenreeks in CSV-indeling. Mogelijk geeft u de voorkeur aan een lege tekenreeks, zelfs in tekstindeling voor gevallen waarin u null-waarden niet wilt onderscheiden van lege tekenreeksen.
koptekst
Hiermee geeft u op dat het bestand een koptekstregel bevat met de namen van elke kolom in het bestand. In de uitvoer bevat de eerste regel de kolomnamen uit de tabel.
citaat
Hiermee geeft u het aanhalingsteken op dat moet worden gebruikt wanneer een gegevenswaarde wordt aanhalingstekens. De standaardwaarde is dubbele aanhalingstekens. Het moet één byteteken zijn.
escape
Hiermee geeft u het teken op dat moet worden weergegeven vóór een gegevensteken dat overeenkomt met de prijsopgavewaarde. De standaardwaarde is hetzelfde als de prijsopgavewaarde (zodat het aanhalingsteken wordt verdubbeld als het in de gegevens wordt weergegeven). Het moet één byteteken zijn.
force_quote
Dwingt af dat het quoteren moet worden gebruikt voor alle niet-NULL-waarden in elke opgegeven kolom. Null-uitvoer wordt nooit geciteerd. Als * is opgegeven, worden niet-NULL-waarden in alle kolommen vermeld.
force_not_null
Komt niet overeen met de waarden van de opgegeven kolommen ten opzichte van de null-tekenreeks. In het standaardscenario waarin de null-tekenreeks leeg is, betekent dit dat lege waarden worden gelezen als tekenreeksen met de lengte nul in plaats van nullen, zelfs wanneer ze niet worden geciteerd.
force_null
Koppel de waarden van de opgegeven kolommen aan de null-tekenreeks, zelfs als deze is geciteerd en als er een overeenkomst wordt gevonden, stelt u de waarde in op NULL. In het standaardscenario waarin de null-tekenreeks leeg is, wordt een lege tekenreeks tussen aanhalingstekens omgezet in NULL.
content_encoding
Hiermee geeft u op dat het bestand is gecodeerd in de encoding_name. Als de optie wordt weggelaten, wordt de huidige clientcodering gebruikt.
Retourtype
jsonb
azure_storage.options_tsv
De functie fungeert als een hulpprogrammafunctie die wordt aangeroepen als een parameter binnen blob_get. Het is handig voor het decoderen van de tsv-inhoud.
azure_storage.options_tsv
(delimiter text DEFAULT NULL::text
,null_string text DEFAULT NULL::text
,content_encoding text DEFAULT NULL::text
)
Returns jsonb;
Argumenten
scheidingsteken
Hiermee geeft u het teken op dat kolommen in elke rij (regel) van het bestand scheidt. De standaardwaarde is een tabteken in tekstindeling, een komma in CSV-indeling. Het moet één byteteken zijn.
null_string
Hiermee geeft u de tekenreeks die een null-waarde vertegenwoordigt. De standaardwaarde is \N (backslash-N) in tekstindeling en een niet-aanhalingstekenloze lege tekenreeks in CSV-indeling. Mogelijk geeft u de voorkeur aan een lege tekenreeks, zelfs in tekstindeling voor gevallen waarin u null-waarden niet wilt onderscheiden van lege tekenreeksen.
content_encoding
Hiermee geeft u op dat het bestand is gecodeerd in de encoding_name. Als de optie wordt weggelaten, wordt de huidige clientcodering gebruikt.
Retourtype
jsonb
azure_storage.options_binary
De functie fungeert als een hulpprogrammafunctie die wordt aangeroepen als een parameter binnen blob_get. Het is handig voor het decoderen van de binaire inhoud.
azure_storage.options_binary
(content_encoding text DEFAULT NULL::text)
Returns jsonb;
Argumenten
content_encoding
Hiermee geeft u op dat het bestand is gecodeerd in de encoding_name. Als deze optie wordt weggelaten, wordt de huidige clientcodering gebruikt.
Retourtype
jsonb
Notitie
Met machtigingen kunt u nu containers weergeven die zijn ingesteld op toegangsniveaus voor privé- en blobtoegang voor die opslag, maar alleen als de citus user, waaraan de azure_storage_admin rol is verleend. Als u een nieuwe gebruiker met de naam Support maakt, is het niet standaard toegestaan om toegang te krijgen tot de inhoud van de container.
Voorbeelden
De voorbeelden die worden gebruikt, maken gebruik van een voorbeeld van een Azure-opslagaccount (pgquickstart) met aangepaste bestanden die zijn geüpload om toe te voegen aan de dekking van verschillende gebruiksvoorbeelden. We kunnen beginnen met het maken van een tabel die wordt gebruikt in de set met voorbeelden.
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
);
Toegangssleutel van opslagaccount toevoegen (verplicht voor toegangsniveau = privé)
In het voorbeeld ziet u hoe u toegangssleutel voor het opslagaccount toevoegt om toegang te krijgen tot query's vanuit een sessie in het Azure Cosmos DB voor Postgres-cluster.
SELECT azure_storage.account_add('pgquickstart', 'SECRET_ACCESS_KEY');
Tip
Open toegangssleutels in uw opslagaccount. Kopieer de naam van het opslagaccount en kopieer de sleutel uit de sectie Sleutel1 (u moet eerst Weergeven naast de sleutel selecteren).
Toegangssleutel van opslagaccount verwijderen
In het voorbeeld ziet u hoe u de toegangssleutel voor een opslagaccount verwijdert. Deze actie resulteert in het verwijderen van toegang tot bestanden die worden gehost in een privé-bucket in de container.
SELECT azure_storage.account_remove('pgquickstart');
Toegang voor een rol toevoegen aan Azure Blob Storage
SELECT * FROM azure_storage.account_user_add('pgquickstart', 'support');
Alle rollen weergeven met toegang in Azure Blob Storage
SELECT * FROM azure_storage.account_list();
De rollen verwijderen met toegang in Azure Blob Storage
SELECT * FROM azure_storage.account_user_remove('pgquickstart', 'support');
De objecten in een public container weergeven
SELECT * FROM azure_storage.blob_list('pgquickstart','publiccontainer');
De objecten in een private container weergeven
SELECT * FROM azure_storage.blob_list('pgquickstart','privatecontainer');
Notitie
Het toevoegen van een toegangssleutel is verplicht.
De objecten weergeven met specifieke tekenreeks initialen binnen een openbare container
SELECT * FROM azure_storage.blob_list('pgquickstart','publiccontainer','e');
Alternatief
SELECT * FROM azure_storage.blob_list('pgquickstart','publiccontainer') WHERE path LIKE 'e%';
Inhoud lezen van een object in een container
Met de blob_get functie wordt een bestand opgehaald uit blobopslag. Om blob_get te laten weten hoe u de gegevens kunt parseren, kunt u een waarde (NULL::table_name) doorgeven die dezelfde indeling heeft als het bestand.
SELECT * FROM azure_storage.blob_get
('pgquickstart'
,'publiccontainer'
,'events.csv.gz'
, NULL::events)
LIMIT 5;
U kunt ook expliciet de kolommen in de FROM component definiëren.
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;
Decoderoptie gebruiken
In het voorbeeld ziet u het gebruik van decoder de optie. Normaal gesproken wordt de indeling afgeleid van de extensie van het bestand, maar wanneer de bestandsinhoud geen overeenkomende extensie heeft, kunt u het argument decoder doorgeven.
SELECT * FROM azure_storage.blob_get
('pgquickstart'
,'publiccontainer'
,'events'
, NULL::events
, decoder := 'csv')
LIMIT 5;
Compressie gebruiken met decoderoptie
In het voorbeeld ziet u hoe u het gebruik van de gzip-compressie kunt afdwingen op een gecomprimeerd gzip-bestand zonder een standaard-.gz-extensie.
SELECT * FROM azure_storage.blob_get
('pgquickstart'
,'publiccontainer'
,'events-compressed'
, NULL::events
, decoder := 'csv'
, compression := 'gzip')
LIMIT 5;
Gefilterde inhoud importeren en wijzigen voordat u laadt vanuit csv-indelingsobject
In het voorbeeld ziet u de mogelijkheid om de inhoud die wordt geïmporteerd uit het object in de container te filteren en te wijzigen voordat deze in een SQL-tabel wordt geladen.
SELECT concat('P-',event_id::text) FROM azure_storage.blob_get
('pgquickstart'
,'publiccontainer'
,'events.csv'
, NULL::events)
WHERE event_type='PushEvent'
LIMIT 5;
Query's uitvoeren op inhoud uit bestand met kopteksten, aangepaste scheidingstekens, escapetekens
U kunt aangepaste scheidingstekens en escapetekens gebruiken door het resultaat van azure_storage.options_copy het options argument door te geven.
SELECT * FROM azure_storage.blob_get
('pgquickstart'
,'publiccontainer'
,'events_pipe.csv'
,NULL::events
,options := azure_storage.options_csv_get(delimiter := '|' , header := 'true')
);
Aggregatiequery voor inhoud van een object in de container
Op deze manier kunt u query's uitvoeren op gegevens zonder deze te importeren.
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;