Konektor Common Data Model Sparku pro Azure Synapse Analytics

Konektor Common Data Model Sparku (konektor CDM Sparku) je čtečka a zapisovač formátu ve službě Azure Synapse Analytics. Umožňuje programu Spark číst a zapisovat entity modelu Common Data Model ve složce Common Data Model prostřednictvím datových rámců Spark.

Informace o definování dokumentů modelu Common Data Model pomocí Modelu Common Data Model 1.2 najdete v tomto článku o tom, co je Common Data Model a jak ho používat.

Možnosti

Konektor na vysoké úrovni podporuje:

• 3.1 a 3.2 a 3.3.
• Čtení dat z entity ve složce Common Data Model do datového rámce Spark
• Zápis ze sparkového datového rámce do entity ve složce Common Data Model založené na definici entity Modelu Common Data Model.
• Zápis ze sparkového datového rámce do entity ve složce Modelu Common Data Model na základě schématu datového rámce.

Konektor podporuje také tyto prvky:

• Čtení a zápis do složek Common Data Model ve službě Azure Data Lake Storage s povoleným hierarchickým oborem názvů (HNS).
• Čtení ze složek Common Data Model popsaných soubory manifestu nebo model.json
• Zápis do složek Common Data Model popsaných souborem manifestu
• Data ve formátu CSV se záhlavími sloupců nebo bez záhlaví a se znaky oddělovače, které lze vybrat uživatelem.
• Data ve formátu Apache Parquet, včetně vnořených parquet.
• Podmanifesty při čtení a volitelné použití podmanifestů s oborem entity při zápisu.
• Zápis dat prostřednictvím uživatelem upravitelných vzorů oddílů
• Použití spravovaných identit a přihlašovacích údajů ve službě Azure Synapse Analytics
• Překlad umístění aliasů modelu Common Data Model používaných při importech prostřednictvím definic adaptérů Common Data Model popsaných v souboru config.json

Omezení

Konektor nepodporuje následující možnosti a scénáře:

• Paralelní zápisy. Nedoporučujeme je. Ve vrstvě úložiště neexistuje žádný mechanismus uzamčení.
• Programový přístup k metadatům entit po přečtení entity
• Programový přístup k nastavení nebo přepsání metadat při psaní entity
• Posun schématu, kdy data v datovém rámci, který se zapisuje, zahrnují další atributy, které nejsou zahrnuty v definici entity.
• Vývoj schématu, kdy oddíly entit odkazují na různé verze definice entity. Verzi můžete ověřit spuštěním příkazu com.microsoft.cdm.BuildInfo.version.
• Podpora zápisu pro model.json
• Zápis Time dat do Parquetu Konektor v současné době podporuje přepsání sloupce časového razítka, který se má interpretovat jako hodnota modelu Common Data Model Time , a DateTime nikoli jako hodnotu pouze pro soubory CSV.
• Typ Parquet Map , pole primitivních typů a pole typů pole. Common Data Model je v současné době nepodporuje, takže ani konektor CDM Sparku nepodporuje.

Ukázky

Pokud chcete začít používat konektor, podívejte se na ukázkový kód a soubory Common Data Model.

Čtení dat

Když konektor čte data, používá metadata ve složce Common Data Model k vytvoření datového rámce na základě definice přeložené entity pro zadanou entitu, jak je uvedeno v manifestu. Konektor používá názvy atributů entity jako názvy sloupců datového rámce. Mapuje datové typy atributů na datové typy sloupců. Při načtení datového rámce se naplní z oddílů entit identifikovaných v manifestu.

Konektor hledá v zadaném manifestu a všechny podmanifesty první úrovně pro zadanou entitu. Pokud je požadovaná entita v podmanifestu druhé nebo nižší nebo pokud existuje více entit se stejným názvem v různých podmanifestech, měli byste zadat podmanifest, který obsahuje požadovanou entitu, a ne kořenový manifest.

Oddíly entit můžou být v kombinaci formátů (například CSV a Parquet). Všechny datové soubory entity identifikované v manifestu se zkombinují do jedné datové sady bez ohledu na formát a načtou se do datového rámce.

Když konektor čte data CSV, použije ve výchozím nastavení možnost Spark failfast . Pokud se počet sloupců nerovná počtu atributů v entitě, konektor vrátí chybu.

Kromě toho konektor od verze 0.19 podporuje režim permissive (pouze pro soubory CSV). Pokud má řádek CSV nižší počet sloupců než schéma entity, konektor přiřazuje chybějícím sloupcům hodnoty null v režimu permissivního režimu. Pokud má řádek CSV více sloupců než schéma entity, sloupce větší než počet sloupců schématu entit jsou zkráceny na počet sloupců schématu schématu. Použití je následující:

.option("mode", "permissive") or .option("mode", "failfast")

Zápis dat

Když konektor zapíše do složky Common Data Model, pokud entita v této složce ještě neexistuje, konektor vytvoří novou entitu a definici. Přidá entitu a definici do složky Common Data Model a odkazuje na ně v manifestu.

Konektor podporuje dva režimy zápisu:

• Explicitní zápis: Definice fyzické entity je založená na logické definici entity Modelu Common Data Model, kterou zadáte.

  Konektor přečte a přeloží zadanou definici logické entity a vytvoří definici fyzické entity použitou ve složce Common Data Model. Pokud příkazy importu v libovolném přímo nebo nepřímo odkazovaném definičním souboru Common Data Model zahrnují aliasy, musíte zadat config.json soubor, který tyto aliasy mapuje na adaptéry a umístění úložiště Common Data Model.

  • Pokud schéma datového rámce neodpovídá definici odkazované entity, konektor vrátí chybu. Ujistěte se, že datové typy sloupců v datovém rámci odpovídají datovým typům atributů v entitě, včetně desetinných dat, přesnosti a škálovací sady prostřednictvím vlastností v Common Data Modelu.
  • Pokud je datový rámec nekonzistentní s definicí entity, konektor vrátí chybu.
  • Pokud je datový rámec konzistentní:
    • Pokud entita již v manifestu existuje, konektor přeloží zadanou definici entity a ověří ji proti definici ve složce Common Data Model. Pokud se definice neshodují, konektor vrátí chybu. Jinak konektor zapíše data a aktualizuje informace o oddílu v manifestu.
    • Pokud entita ve složce Common Data Model neexistuje, konektor zapíše přeloženou kopii definice entity do manifestu ve složce Common Data Model. Konektor zapíše data a aktualizuje informace o oddílu v manifestu.

• Implicitní zápis: Definice entity je odvozena ze struktury datového rámce.

  • Pokud entita ve složce Common Data Model neexistuje, konektor použije implicitní definici k vytvoření definice přeložené entity v cílové složce Common Data Model.

  • Pokud entita existuje ve složce Common Data Model, konektor ověří implicitní definici proti existující definici entity. Pokud se definice neshodují, konektor vrátí chybu. V opačném případě konektor zapíše data a zapíše odvozené definice logické entity do podsložky složky entity.

    Konektor zapisuje data do datových složek v podsložce entity. Režim ukládání určuje, zda se nová data přepíší nebo jsou připojena k existujícím datům, nebo pokud existují data, vrátí se chyba. Výchozí hodnota je vrátit chybu, pokud data již existují.

Integrace aliasů Common Data Model

Definiční soubory modelu Common Data Model používají aliasy v příkazech importu ke zjednodušení příkazů importu a umožňují, aby umístění importovaného obsahu bylo zpožděné v době běhu. Použití aliasů:

• Usnadňuje snadnou organizaci souborů Common Data Model tak, aby související definice modelu Common Data Model bylo možné seskupit do různých umístění.
• Umožňuje přístup k obsahu Common Data Model z různých nasazených umístění za běhu.

Následující fragment kódu ukazuje použití aliasů v příkazech importu v definičním souboru modelu Common Data Model:

"imports": [  
{     
  "corpusPath": "cdm:/foundations.cdm.json"
},  
{       
  "corpusPath": "core:/TrackedEntity.cdm.json"  
},  
{      
  "corpusPath": "Customer.cdm.json"  
} 
]

Předchozí příklad používá cdm jako alias pro umístění základního souboru Common Data Model. Používá core se jako alias pro umístění definičního TrackedEntity souboru.

Aliasy jsou textové popisky, které se shodují s hodnotou oboru názvů v položce adaptéru v souboru config.json modelu Common Data Model. Položka adaptéru určuje typ adaptéru (například adls, CDN, GitHub, nebo local) a adresu URL, která definuje umístění. Některé adaptéry podporují jiné možnosti konfigurace, jako je vypršení časového limitu připojení. Zatímco aliasy jsou libovolné textové popisky, cdm alias se zpracovává zvláštním způsobem.

Konektor Spark CDM hledá v kořenovém umístění modelu definice entity, aby se soubor config.json načetl. Pokud je soubor config.json v jiném umístění nebo chcete přepsat config.json soubor v kořenovém adresáři modelu, můžete pomocí této možnosti zadat umístění souboru configPath config.json. Soubor config.json musí obsahovat položky adaptéru pro všechny aliasy používané v kódu modelu Common Data Model, který se řeší, nebo konektor hlásí chybu.

Možnost přepsat config.json soubor znamená, že pro definice common data modelu můžete poskytnout umístění přístupná k modulu runtime. Ujistěte se, že obsah, na který se odkazuje za běhu, je konzistentní s definicemi, které byly použity při původním vytvoření modelu Common Data Model.

Alias podle konvence cdm odkazuje na umístění standardních definic modelu Common Data Model na kořenové úrovni, včetně souboru foundations.cdm.json . Tento soubor obsahuje primitivní datové typy modelu Common Data Model a základní sadu definic vlastností vyžadovaných pro většinu definic entit modelu Common Data Model.

Alias můžete přeložit cdm stejně jako jakýkoli jiný alias pomocí položky adaptéru v souboru config.json . Pokud nezadáte adaptér nebo zadáte položku s hodnotou null, cdm alias se ve výchozím nastavení přeloží na veřejnou síť pro doručování obsahu modelu Common Data Model (CDN) na adrese https://cdm-schema.microsoft.com/logical/.

Můžete také použít cdmSource možnost přepsání způsobu řešení aliasu cdm . cdmSource Použití této možnosti je užitečné, pokud cdm je alias jediným aliasem používaným v definicích modelu Common Data Model, které se řeší, protože se může vyhnout nutnosti vytvářet nebo odkazovat na soubor config.json.

Parametry, možnosti a režim ukládání

Pro čtení i zápisy zadáte název knihovny konektoru CDM Sparku jako parametr. Pomocí sady možností parametrizujete chování konektoru. Když píšete, konektor také podporuje režim ukládání.

Název knihovny konektoru, možnosti a režim uložení jsou formátované takto:

• dataframe.read.format("com.microsoft.cdm") [.option("option", "value")]*
• dataframe.write.format("com.microsoft.cdm") [.option("option", "value")]* .mode(savemode.\<saveMode\>)

Tady je příklad, který ukazuje některé možnosti použití konektoru pro čtení:

val readDf = spark.read.format("com.microsoft.cdm")
  .option("storage", "mystorageaccount.dfs.core.windows.net")
  .option("manifestPath", "customerleads/default.manifest.cdm.json")
  .option("entity", "Customer")
  .load()

Běžné možnosti čtení a zápisu

Následující možnosti identifikují entitu ve složce Common Data Model, do které čtete nebo do které píšete.

Možnost	Popis	Vzor a ukázkové použití
storage	Adresa URL koncového bodu pro účet Azure Data Lake Storage s povolenou službou HNS, která obsahuje složku Common Data Model. dfs.core.windows.net Použijte adresu URL.	<accountName>.dfs.core.windows.net "myAccount.dfs.core.windows.net"
manifestPath	Relativní cesta k manifestu nebo souboru model.json v účtu úložiště. Pro čtení to může být kořenový manifest nebo podmanifest nebo model.json soubor. Pro zápisy musí být kořenový manifest.	<container>/{<folderPath>}<manifestFileName>, "mycontainer/default.manifest.cdm.json" "models/hr/employees.manifest.cdm.json" "models/hr/employees/model.json" (jen pro čtení)
entity	Název zdrojové nebo cílové entity v manifestu. Při prvním zápisu entity do složky dává konektor definici přeložené entity tento název. V názvu entity se rozlišují malá a velká písmena.	<entityName> "customer"
maxCDMThreads	Maximální počet souběžných čtení, zatímco konektor přeloží definici entity.	Jakékoli platné celé číslo, například 5

Poznámka:

Kromě definice fyzické entity ve složce Common Data Model při čtení už nemusíte zadávat definici logické entity.

Explicitní možnosti zápisu

Následující možnosti identifikují definici logické entity pro zapsanou entitu. Definice logické entity se přeloží na fyzickou definici, která definuje způsob zápisu entity.

Možnost	Popis	Použití vzoru nebo příkladu
entityDefinitionStorage	Účet Azure Data Lake Storage, který obsahuje definici entity. Vyžaduje se, pokud se liší od účtu úložiště, který je hostitelem složky Common Data Model.	<accountName>.dfs.core.windows.net "myAccount.dfs.core.windows.net"
entityDefinitionModelRoot	Umístění kořene modelu nebo korpusu v rámci účtu.	<container>/<folderPath> "crm/core"
entityDefinitionPath	Umístění entity. Je to cesta k souboru definice common data modelu vzhledem ke kořenovému adresáři modelu, včetně názvu entity v tomto souboru.	<folderPath>/<entityName>.cdm.json/<entityName> "sales/customer.cdm.json/customer"
configPath	Cesta ke kontejneru a složce k souboru config.json , který obsahuje konfigurace adaptérů pro všechny aliasy zahrnuté v definičním souboru entity a všechny přímo nebo nepřímo odkazované soubory Modelu Common Data Model. Tato možnost se nevyžaduje, pokud je config.json v kořenové složce modelu.	<container><folderPath>
useCdmStandardModelRoot	Označuje, že kořen modelu je umístěn v https://cdm-schema.microsoft.com/CDM/logical/umístění . Slouží k odkazování na typy entit definovaných v CDN modelu Common Data Model. Přepsání entityDefinitionStorage a entityDefinitionModelRoot (pokud je zadáno)	"useCdmStandardModelRoot"
cdmSource	Definuje, jak cdm se alias (pokud se nachází v definičních souborech Common Data Model) vyřešený. Pokud použijete tuto možnost, přepíše všechny cdm adaptéry zadané v souboru config.json . Hodnoty jsou builtin nebo referenced. Výchozí hodnota je referenced. Pokud tuto možnost nastavíte na referenced, konektor použije nejnovější publikované standardní definice modelu Common Data Model na adrese https://cdm-schema.microsoft.com/logical/. Pokud tuto možnost nastavíte na builtin, konektor použije základní definice Modelu Common Data Model integrované do objektového modelu Common Data Model, který konektor používá. Poznámka: * Konektor Spark CDM nemusí používat nejnovější sadu SDK modelu Common Data Model, takže nemusí obsahovat nejnovější publikované standardní definice. * Integrované definice zahrnují pouze obsah Common Data Model nejvyšší úrovně, například foundations.cdm.json nebo primitives.cdm.json. Pokud chcete použít definice Common Data Model nižší úrovně, použijte referenced nebo zahrňte cdm adaptér do config.json.	"builtin"|"referenced"

V předchozím příkladu je https://myAccount.dfs.core.windows.net/models/crm/core/sales/customer.cdm.json/customerúplná cesta k objektu definice entity zákazníka . V této cestě jsou modely kontejnerem ve službě Azure Data Lake Storage.

Možnosti implicitního zápisu

Pokud při zápisu nezadáte definici logické entity, zapíše se entita implicitně na základě schématu datového rámce.

Když píšete implicitně, sloupec časového razítka se obvykle interpretuje jako datový typ Common Data Model DateTime . Tuto interpretaci můžete přepsat tak, že vytvoříte atribut datového typu Common Data Model Time tím, že zadáte objekt metadat přidružený ke sloupci, který určuje datový typ. Podrobnosti najdete v části Zpracování časových dat modelu Common Data Model dále v tomto článku.

Podpora zápisu dat o čase existuje pouze pro soubory CSV. Tato podpora se v současné době nevztahuje na Parquet.

Možnosti struktury složek a formátu dat

Ke změně formátu složky a formátu souboru můžete použít následující možnosti.

Možnost	Popis	Použití vzoru nebo příkladu
useSubManifest	Pokud true, způsobí, že cílová entita bude zahrnuta do kořenového manifestu prostřednictvím podmanifestu. Podmanifest a definice entity jsou zapsány do složky entity pod kořenem. Výchozí hodnota je false.	"true"|"false"
format	Definuje formát souboru. Aktuální podporované formáty souborů jsou CSV a Parquet. Výchozí hodnota je csv.	"csv"|"parquet"
delimiter	Jenom sdílený svazek clusteru. Definuje oddělovač, který používáte. Výchozí hodnota je čárka.	"|"
columnHeaders	Jenom sdílený svazek clusteru. Pokud truepřidá první řádek do datových souborů se záhlavími sloupců. Výchozí hodnota je true.	"true"|"false"
compression	Jen napsat. Pouze Parquet. Definuje formát komprese, který používáte. Výchozí hodnota je snappy.	"uncompressed" | "snappy" | "gzip" | "lzo"
dataFolderFormat	Umožňuje definovatelnou strukturu složek dat v rámci složky entity. Umožňuje nahradit hodnoty data a času názvy složek pomocí DateTimeFormatter formátování. Obsah bez formátu musí být uzavřený do jednoduchých uvozovek. Výchozí formát je "yyyy"-"MM"-"dd", který vytváří názvy složek jako 2020-07-30.	year "yyyy" / month "MM" "Data"

Režim uložení

Režim ukládání určuje, jak konektor zpracovává existující data entit ve složce Common Data Model při psaní datového rámce. Možnosti jsou přepsání, připojení nebo vrácení chyby, pokud data již existují. Výchozí režim ukládání je ErrorIfExists.

Režimu	Popis
SaveMode.Overwrite	Přepíše definici existující entity, pokud se změní, a nahradí existující datové oddíly datovými oddíly zapsaných datovými oddíly.
SaveMode.Append	Připojí data, která se zapisují v nových oddílech, spolu s existujícími oddíly. Tento režim nepodporuje změnu schématu. Pokud schéma zapisovaných dat není kompatibilní s definicí existující entity, konektor vyvolá chybu.
SaveMode.ErrorIfExists	Pokud oddíly již existují, vrátí chybu.

Podrobnosti o pojmenování a uspořádání datových souborů při zápisu najdete v části složek a pojmenování souborů a organizace dále v tomto článku.

Ověřování

Pomocí tří režimů ověřování s konektorem CDM Sparku můžete číst nebo zapisovat metadata a oddíly datového modelu Common Data Model: předávání přihlašovacích údajů, token sdíleného přístupového podpisu (SAS) a registraci aplikace.

Předávání přihlašovacích údajů

V Azure Synapse Analytics konektor Spark CDM podporuje použití spravovaných identit pro prostředky Azure k mediaci přístupu k účtu Azure Data Lake Storage, který obsahuje složku Common Data Model. Spravovaná identita se automaticky vytvoří pro každý pracovní prostor Azure Synapse Analytics. Konektor používá spravovanou identitu pracovního prostoru, který obsahuje poznámkový blok, ve kterém je konektor volána k ověření účtů úložiště.

Musíte zajistit, aby vybraná identita měl přístup k příslušným účtům úložiště:

• Udělte přispěvateli dat objektů blob služby Storage oprávnění, aby knihovna mohla zapisovat do složek Common Data Model.
• Udělte čtenáři dat objektů blob služby Storage oprávnění k povolení přístupu jen pro čtení.

V obou případech nejsou vyžadovány žádné další možnosti konektoru.

Možnosti řízení přístupu na základě tokenu SAS

Přihlašovací údaje tokenu SAS jsou další možností ověřování účtů úložiště. S ověřováním tokenu SAS může být token SAS na úrovni kontejneru nebo složky. Jsou vyžadována příslušná oprávnění:

• Oprávnění ke čtení pro manifest nebo oddíl potřebují pouze podporu na úrovni čtení.
• Oprávnění k zápisu potřebují podporu čtení i zápisu.

Možnost	Popis	Vzor a ukázkové použití
sasToken	Token SAS pro přístup k relativnímu účtu úložiště se správnými oprávněními	<token>

Možnosti pro řízení přístupu na základě přihlašovacích údajů

Jako alternativu k použití spravované identity nebo identity uživatele můžete zadat explicitní přihlašovací údaje, které konektoru Spark CDM umožní přístup k datům. V Microsoft Entra ID vytvořte registraci aplikace. Potom této registraci aplikace udělte přístup k účtu úložiště pomocí některé z následujících rolí:

• Přispěvatel dat objektů blob úložiště, aby knihovna mohla zapisovat do složek Common Data Model
• Čtenář dat v objektech blob služby Storage umožňující jen oprávnění ke čtení

Po vytvoření oprávnění můžete ke každému volání předat ID aplikace, klíč aplikace a ID tenanta konektoru pomocí následujících možností. K uložení těchto hodnot doporučujeme použít Azure Key Vault, abyste měli jistotu, že nejsou uložené ve formátu prostého textu v souboru poznámkového bloku.

Možnost	Popis	Vzor a ukázkové použití
appId	ID registrace aplikace pro ověřování k účtu úložiště	<guid>
appKey	Zaregistrovaný klíč nebo tajný klíč aplikace	<encrypted secret>
tenantId	ID tenanta Microsoft Entra, pod kterým je aplikace zaregistrovaná	<guid>

Příklady

Všechny následující příklady používají appId, appKeya tenantId proměnné. Tyto proměnné jste inicializovali dříve v kódu na základě registrace aplikace Azure: Oprávnění Přispěvatel dat v objektech blob služby Storage v úložišti pro zápis a oprávnění Čtenář dat objektů blob služby Storage pro čtení.

Čteno

Tento kód načte entitu Person ze složky Common Data Model s manifestem v mystorage.dfs.core.windows.net/cdmdata/contacts/root.manifest.cdm.json:

val df = spark.read.format("com.microsoft.cdm")
 .option("storage", "mystorage.dfs.core.windows.net")
 .option("manifestPath", "cdmdata/contacts/root.manifest.cdm.json")
 .option("entity", "Person")
 .load()

Implicitní zápis pouze pomocí schématu datového rámce

Následující kód zapíše df datový rámec do složky Common Data Model s manifestem s mystorage.dfs.core.windows.net/cdmdata/Contacts/default.manifest.cdm.json entitou události.

Kód zapíše data událostí jako soubory Parquet, zkomprimuje je pomocí gzipa připojí je ke složce. (Kód přidá nové soubory bez odstranění existujících souborů.)

df.write.format("com.microsoft.cdm")
 .option("storage", "mystorage.dfs.core.windows.net")
 .option("manifestPath", "cdmdata/Contacts/default.manifest.cdm.json")
 .option("entity", "Event")
 .option("format", "parquet")
 .option("compression", "gzip")
 .mode(SaveMode.Append)
 .save()

Explicitní zápis pomocí definice entity uložené ve službě Data Lake Storage

Následující kód zapíše df datový rámec do složky Common Data Model s manifestem u https://_mystorage_.dfs.core.windows.net/cdmdata/Contacts/root.manifest.cdm.jsonPerson entity. Kód zapisuje data osob jako nové soubory CSV (ve výchozím nastavení), které přepíší existující soubory ve složce.

Kód načte definici Person entity z https://_mystorage_.dfs.core.windows.net/models/cdmmodels/core/Contacts/Person.cdm.json.

df.write.format("com.microsoft.cdm")
 .option("storage", "mystorage.dfs.core.windows.net")
 .option("manifestPath", "cdmdata/contacts/root.manifest.cdm.json")
 .option("entity", "Person")
 .option("entityDefinitionModelRoot", "cdmmodels/core")
 .option("entityDefinitionPath", "/Contacts/Person.cdm.json/Person")
 .mode(SaveMode.Overwrite)
 .save()

Explicitní zápis pomocí entity definované v úložišti GitHubu Common Data Model

Následující kód zapíše df datový rámec do složky Common Data Model pomocí:

• Manifest na https://_mystorage_.dfs.core.windows.net/cdmdata/Teams/root.manifest.cdm.jsonadrese .
• Podadresář, který obsahuje entitu TeamMembership vytvořenou v podadresáři TeamMembership .

TeamMembership data se zapisují do souborů CSV (výchozí nastavení), které přepíší všechny existující datové soubory. Kód načte definici TeamMembership entity z CDN modelu Common Data Model při členství v týmu v aplikaciCommon.

df.write.format("com.microsoft.cdm")
 .option("storage", "mystorage.dfs.core.windows.net")
 .option("manifestPath", "cdmdata/Teams/root.manifest.cdm.json")
 .option("entity", "TeamMembership")
 .option("useCdmStandardModelRoot", true)
 .option("entityDefinitionPath", "core/applicationCommon/TeamMembership.cdm.json/TeamMembership")
 .option("useSubManifest", true)
 .mode(SaveMode.Overwrite)
 .save()

Ostatní úvahy

Mapování datových typů ze Sparku na Common Data Model

Konektor použije následující mapování datových typů při převodu modelu Common Data Model na Spark nebo z Sparku.

Spark	Common Data Model
ShortType	SmallInteger
IntegerType	Integer
LongType	BigInteger
DateType	Date
Timestamp	DateTime (volitelně Time)
StringType	String
DoubleType	Double
DecimalType(x,y)	Decimal (x,y) (výchozí měřítko a přesnost jsou 18,4)
FloatType	Float
BooleanType	Boolean
ByteType	Byte

Konektor nepodporuje datový typ Common Data Model Binary .

Zpracování dat modelu Common Data Model, DateTime a DateTimeOffset

Konektor Spark CDM zpracovává Common Data Model Date a DateTime datové typy jako normální pro Spark a Parquet. Ve formátu CSV konektor čte a zapisuje tyto datové typy ve formátu ISO 8601.

Konektor interpretuje hodnoty datového typu Common Data Model DateTime jako UTC. Ve formátu CSV zapisuje konektor tyto hodnoty ve formátu ISO 8601. Příklad: 2020-03-13 09:49:00Z.

Hodnoty modelu Common Data Model DateTimeOffset určené pro zaznamenávání instancí místního času se zpracovávají odlišně ve Sparku a Parquetu ze souboru CSV. Csv a další formáty můžou vyjádřit místní čas okamžitě jako strukturu, která se skládá z data a času, například 2020-03-13 09:49:00-08:00. Parquet a Spark takové struktury nepodporují. Místo toho používají TIMESTAMP datový typ, který umožňuje okamžité zaznamenání v UTC (nebo v nezadaném časovém pásmu).

Konektor Spark CDM převede DateTimeOffset hodnotu ve formátu CSV na časové razítko UTC. Tato hodnota se v Parquet zachová jako časové razítko. Pokud se hodnota později uloží do sdíleného svazku clusteru, bude serializována jako DateTimeOffset hodnota s posunem +00:00. Nedojde ke ztrátě dočasné přesnosti. Serializované hodnoty představují stejnou instanci jako původní hodnoty, i když posun je ztracen.

Systémy Spark používají svůj systémový čas jako směrný plán a obvykle vyjadřují čas pomocí daného místního času. Časy UTC je možné vždy vypočítat prostřednictvím aplikace posunu místního systému. Pro systémy Azure ve všech oblastech je systémový čas vždy UTC, takže všechny hodnoty časového razítka jsou obvykle v UTC. Pokud používáte implicitní zápis, kde je definice Common Data Model odvozena z datového rámce, sloupce časového razítka se přeloží na atributy s datovým typem Common Data Model DateTime , což znamená čas UTC.

Pokud je důležité zachovat místní čas a data se budou zpracovávat ve Sparku nebo se zachovají v Parquet, doporučujeme použít DateTime atribut a zachovat posun v samostatném atributu. Můžete například ponechat posun jako celočíselnou hodnotu se signi čísly, která představuje minuty. V modelu Common Data Model jsou hodnoty DateTime ve standardu UTC, takže je nutné použít posun na výpočetní místní čas.

Ve většině případů není zachování místního času důležité. Místní časy se často vyžadují jenom v uživatelském rozhraní pro pohodlí uživatelů a na základě časového pásma uživatele, takže uložení času UTC je často lepším řešením.

Zpracování časových dat modelu Common Data Model

Spark nepodporuje explicitní Time datový typ. Atribut s datovým typem Common Data Model Time je reprezentován v datovém rámci Sparku jako sloupec s datovým typem Timestamp . Když konektor Spark CDM přečte časovou hodnotu, časové razítko v datovém rámci se inicializuje s datem epochy Sparku 01/01/1970 a hodnotou času jako přečtenou ze zdroje.

Když použijete explicitní zápis, můžete sloupec časového razítka namapovat na atribut nebo Time sloupec s časovým razítkemDateTime. Pokud namapujete časové razítko na Time atribut, část data časového razítka se odstraní.

Pokud použijete implicitní zápis, ve výchozím nastavení se sloupec časového razítka mapuje na DateTime atribut. Pokud chcete namapovat sloupec časového razítka na Time atribut, musíte do sloupce v datovém rámci přidat objekt metadat, který označuje, že časové razítko by mělo být interpretováno jako časová hodnota. Následující kód ukazuje, jak to provést v jazyce Scala:

val md = new MetadataBuilder().putString(“dataType”, “Time”)
val schema = StructType(List(
StructField(“ATimeColumn”, TimeStampType, true, md))

Přesnost časových hodnot

Konektor Spark CDM podporuje časové hodnoty v obou DateTime nebo Time. Sekundy mají až šest desetinných míst na základě formátu dat v souboru, který se čte (CSV nebo Parquet) nebo definovaných v datovém rámci. Použití šesti desetinných míst umožňuje přesnost od jednoho sekund po mikrosekundy.

Pojmenování a uspořádání složek a souborů

Když píšete do složek Common Data Model, existuje výchozí organizace složek. Ve výchozím nastavení se datové soubory zapisují do složek vytvořených pro aktuální datum s názvem 2010-07-31. Pomocí této možnosti můžete přizpůsobit strukturu a názvy dateFolderFormat složek.

Názvy datových souborů jsou založeny na následujícím vzoru: <entity-jobid>><-*.<fileformat>.

Pomocí metody můžete řídit počet datových oddílů, které jsou zapsány sparkContext.parallelize() . Počet oddílů se určuje buď počtem exekutorů v clusteru Spark, nebo explicitně zadaným. Následující příklad Scala vytvoří datový rámec se dvěma oddíly:

val df= spark.createDataFrame(spark.sparkContext.parallelize(data, 2), schema)

Tady je příklad explicitního zápisu, který je definovaný definicí odkazované entity:

+-- <CDMFolder>
     |-- default.manifest.cdm.json     << with entity reference and partition info
     +-- <Entity>
          |-- <entity>.cdm.json        << resolved physical entity definition
          |-- <data folder>
          |-- <data folder>
          +-- ...                            

Tady je příklad explicitního zápisu s podmanifestem:

+-- <CDMFolder>
    |-- default.manifest.cdm.json       << contains reference to submanifest
    +-- <Entity>
         |-- <entity>.cdm.json
         |-- <entity>.manifest.cdm.json << submanifest with partition info
         |-- <data folder>
         |-- <data folder>
         +-- ...

Tady je příklad implicitního zápisu, ve kterém je definice entity odvozena ze schématu datového rámce:

+-- <CDMFolder>
    |-- default.manifest.cdm.json
    +-- <Entity>
         |-- <entity>.cdm.json          << resolved physical entity definition
         +-- LogicalDefinition
         |   +-- <entity>.cdm.json      << logical entity definitions
         |-- <data folder>
         |-- <data folder>
         +-- ...

Tady je příklad implicitního zápisu s podmanifestem:

+-- <CDMFolder>
    |-- default.manifest.cdm.json       << contains reference to submanifest
    +-- <Entity>
        |-- <entity>.cdm.json           << resolved physical entity definition
        |-- <entity>.manifest.cdm.json  << submanifest with reference to the entity and partition info
        +-- LogicalDefinition
        |   +-- <entity>.cdm.json       << logical entity definitions
        |-- <data folder>
        |-- <data folder>
        +-- ...

Řešení problémů a známé problémy

• Ujistěte se, že desetinná přesnost a měřítko desetinných polí datového typu, která používáte v datovém rámci, odpovídají datovému typu, který je v definici entity Modelu Common Data Model. Pokud nejsou přesnost a měřítko definovány explicitně v Modelu Common Data Model, výchozí hodnota je Decimal(18,4). U model.json souborů se předpokládá , Decimal že .Decimal(18,4)
• Názvy složek a souborů v následujících možnostech by neměly obsahovat mezery ani speciální znaky, například rovnítko (=): manifestPath, , entityDefinitionModelRootentityDefinitionPath, dataFolderFormat.

Další kroky

Teď se můžete podívat na další konektory Apache Sparku:

• Konektor Apache Spark Kusto
• Konektor Apache Spark SQL