COPY INTO

Van toepassing op: Databricks SQL Databricks Runtime

Laadt gegevens van een bestandslocatie in een Delta-tabel. Dit is een nieuwe poging en idempotente bewerking. Bestanden op de bronlocatie die al zijn geladen, worden overgeslagen. Dit geldt zelfs als de bestanden zijn gewijzigd sinds ze zijn geladen. Zie Algemene patronen voor het laden van gegevens met behulp van COPY INTOvoor voorbeelden.

Syntaxis

COPY INTO target_table [ BY POSITION | ( col_name [ , <col_name> ... ] ) ]
  FROM { source_clause |
         ( SELECT expression_list FROM source_clause ) }
  FILEFORMAT = data_source
  [ VALIDATE [ ALL | num_rows ROWS ] ]
  [ FILES = ( file_name [, ...] ) | PATTERN = glob_pattern ]
  [ FORMAT_OPTIONS ( { data_source_reader_option = value } [, ...] ) ]
  [ COPY_OPTIONS ( { copy_option = value } [, ...] ) ]

source_clause
  source [ WITH ( [ CREDENTIAL { credential_name |
                                 (temporary_credential_options) } ]
                  [ ENCRYPTION (encryption_options) ] ) ]

Parameterwaarden

• target_table

  Identificeert een bestaande Delta-tabel. De target_table mag geen tijdelijke specificatie of optiesspecificatie bevatten.

  Als de tabelnaam wordt opgegeven in de vorm van een locatie, zoals: delta.`/path/to/table` , kan Unity Catalog de toegang beheren tot de locaties waarnaar wordt geschreven. U kunt schrijven naar een externe locatie door:

  • De locatie definiëren als een externe locatie en WRITE FILES machtigingen hebben voor die externe locatie.
  • Beschikken over WRITE FILES machtigingen voor een benoemde opslagreferentie die toestemming geven om naar een locatie te schrijven met behulp van: COPY INTO delta.`/some/location` WITH (CREDENTIAL <named-credential>)

  Zie Verbinding maken met cloudobjectopslag met behulp van Unity Catalog voor meer informatie.

• BY POSITION | ( col_name [ , <col_name> ... ] )

  Bronkolommen worden gekoppeld aan kolommen van de doeltabel op basis van hun ordinale positie. Het type casting van de overeenkomende kolommen wordt automatisch uitgevoerd.

  Deze parameter wordt alleen ondersteund voor de csv-bestandsindeling zonder koptekst. U moet FILEFORMAT = CSV specificeren. FORMAT_OPTIONS moet ook worden ingesteld op ("headers" = "false") (FORMAT_OPTIONS ("headers" = "false") is de standaardinstelling).

  Syntaxisoptie 1: BY POSITION

  • Koppelt automatisch bronkolommen met de kolommen van de doeltabel op basis van volgorde.
    • Standaard naamvergelijking wordt niet gebruikt voor overeenkoming.
    • IDENTITY kolommen en GENERATED kolommen van de doeltabel worden genegeerd wanneer deze overeenkomen met de bronkolommen.
    • Als het aantal bronkolommen niet gelijk is aan de gefilterde doeltabelkolommen, genereert COPY INTO een fout.

  Syntaxisoptie 2: ( col_name [ , <col_name> ... ] )

  • Stemt bronkolommen af op de opgegeven doeltabelkolommen volgens hun relatieve volgorde, door gebruik te maken van een lijst met kolomnamen van de doeltabel tussen haakjes, gescheiden door komma's.
    • De oorspronkelijke volgorde van de tabelkolommen en kolomnamen wordt niet gebruikt voor het matchen.
    • IDENTITY kolommen en GENERATED kolommen kunnen niet worden opgegeven in de lijst met kolomnamen, anders wordt er een fout gegenereerd COPY INTO.
    • De opgegeven kolommen kunnen niet worden gedupliceerd.
    • Als het aantal bronkolommen niet gelijk is aan de opgegeven tabelkolommen, COPY INTO veroorzaakt een fout.
    • Voor de kolommen die niet zijn opgegeven in de lijst met kolomnamen, wijst COPY INTO standaardwaarden toe, indien van toepassing, en wijst anders NULL toe. Als een kolom niet nullbaar is, genereert COPY INTO een fout.

• source

  De bestandslocatie waaruit de gegevens moeten worden geladen. Bestanden op deze locatie moeten de indeling hebben die is opgegeven in FILEFORMAT. De locatie wordt opgegeven in de vorm van een URI.

  Toegang tot de bronlocatie kan worden geboden via:

  • credential_name

    Optionele naam van de referentie die wordt gebruikt voor toegang tot of schrijven naar de opslaglocatie. U gebruikt deze referentie alleen als de bestandslocatie niet is opgenomen in een externe locatie. Zie credential_name.

  • Inline tijdelijke inloggegevens.

  • De bronlocatie definiëren als een externe locatie en READ FILES machtigingen hebben voor de externe locatie via Unity Catalog.
  • Een benoemde opslagreferentie gebruiken met READ FILES permissies die autorisatie bieden om via Unity Catalog vanaf een locatie te lezen.

  U hoeft geen inline- of benoemde referenties op te geven als het pad al als een externe locatie is gedefinieerd en u toestemming hebt om deze te gebruiken. Zie Overzicht van externe locaties voor meer informatie.

  Notitie

  Als het pad naar het bronbestand een hoofdpad is, voegt u bijvoorbeeld een slash (/) toe aan het einde van het bestandspad s3://my-bucket/.

  Geaccepteerde referentieopties zijn:

  • AZURE_SAS_TOKEN voor ADLS en Azure Blob Storage
  • AWS_ACCESS_KEY, AWS_SECRET_KEYen AWS_SESSION_TOKEN voor AWS S3

  Geaccepteerde versleutelingsopties zijn:

  • TYPE = 'AWS_SSE_C'en MASTER_KEY voor AWS S3

Zie Gegevens laden met COPY INTO met tijdelijke referenties.

• SELECT expression_list

  Selecteert de opgegeven kolommen of expressies uit de brongegevens voordat u naar de Delta-tabel kopieert. De expressies kunnen alles zijn wat u gebruikt met SELECT instructies, waaronder vensterbewerkingen. U kunt aggregatie-expressies alleen gebruiken voor globale aggregaten; u kunt geen GROUP BY op kolommen toepassen met deze syntaxis.

• FILEFORMAT = data_source

  De indeling van de bronbestanden die moeten worden geladen. Een van CSV, JSON, AVRO, ORC, PARQUET, TEXT, BINARYFILE.

• VALIDATE

  Van toepassing op: Databricks SQL Databricks Runtime 10.4 LTS en hoger

  De gegevens die in een tabel moeten worden geladen, worden gevalideerd, maar niet naar de tabel geschreven. Deze validaties zijn onder andere:

  • Of de gegevens kunnen worden verwerkt.
  • Of het schema overeenkomt met dat van de tabel of dat het schema moet worden ontwikkeld.
  • Of aan alle nulliteits- en controlevoorwaarden wordt voldaan.

  De standaardinstelling is om alle gegevens te valideren die moeten worden geladen. U kunt een aantal rijen opgeven dat moet worden gevalideerd met het ROWS trefwoord, zoals VALIDATE 15 ROWS. De COPY INTO instructie retourneert een voorbeeld van de gegevens van 50 rijen of minder wanneer een aantal minder dan 50 wordt gebruikt met het ROWS trefwoord).

• FILES

  Een lijst met bestandsnamen die moeten worden geladen, met een limiet van 1000 bestanden. Kan niet worden opgegeven met PATTERN.

• PATTERN

  Een glob-patroon dat de bestanden identificeert die moeten worden geladen vanuit de bronmap. Kan niet worden opgegeven met FILES.

  Patroon	Beschrijving
  ?	Komt overeen met één teken
  *	Komt overeen met nul of meer tekens
  [abc]	Komt overeen met één teken uit de tekenset {a,b,c}.
  [a-z]	Komt overeen met één teken uit het tekenbereik {a... z}.
  [^a]	Komt overeen met één teken dat niet afkomstig is uit de tekenset of het bereik {a}. Houd er rekening mee dat het ^ teken direct rechts van de openende haak moet staan.
  {ab,cd}	Een string die overeenkomt met een element uit de verzameling {ab, cd}.
  {ab,c{de, fh}}	Komt overeen met een tekenreeks in de verzameling van tekenreeksen {ab, cde, cfh}.

• FORMAT_OPTIONS

  Opties die moeten worden doorgegeven aan de Apache Spark-gegevensbronlezer voor de opgegeven indeling. Zie Indelingsopties voor elke bestandsindeling.

• COPY_OPTIONS

  Opties voor het beheren van de bewerking van de COPY INTO opdracht.

  • force: Booleaanse waarde, standaard false. Als deze optie is ingesteld true, is idempotentie uitgeschakeld en worden bestanden geladen, ongeacht of ze eerder zijn geladen.
  • mergeSchema: Booleaanse waarde, standaard false. Als dit is ingesteld op true, kan het schema worden ontwikkeld op basis van de binnenkomende gegevens.

Tegelijkertijd COPY INTO aanroepen

COPY INTO ondersteunt gelijktijdige aanroepen voor dezelfde tabel. Zolang COPY INTO gelijktijdig wordt aangeroepen op afzonderlijke sets van invoerbestanden, moet elke aanroep uiteindelijk succesvol zijn, anders krijgt u een transactieconflict. COPY INTO mag niet gelijktijdig worden aangeroepen om de prestaties te verbeteren; een enkele COPY INTO opdracht met meerdere bestanden presteert doorgaans beter dan het uitvoeren van gelijktijdige COPY INTO opdrachten met elk één bestand. COPY INTO kan gelijktijdig worden aangeroepen wanneer:

• Meerdere gegevensproducenten hebben geen eenvoudige manier om te coördineren en kunnen niet één aanroep maken.
• Wanneer een zeer grote map kan worden opgenomen, submap voor submap. Wanneer u directory's met een zeer groot aantal bestanden opneemt, raadt Databricks het gebruik van Auto Loader indien mogelijk aan.

Metagegevens van access-bestanden

Zie Bestandsmetagegevenskolomvoor informatie over het benaderen van metagegevens voor bestandsgebaseerde gegevensbronnen.

Opmaakopties

Zie de opties voor DataFrameReader voor opties die specifiek zijn voor elke bestandsindeling (JSON, CSV, XML, Parquet, Avro, tekst, ORC en binair).

Verwante artikelen:

• referenties
• VERWIJDEREN
• INSERT
• FUSEREN
• PARTITION
• vraag
• UPDATE
• Aan de slag met COPY INTO om gegevens te laden