Package: acryl-datahub-tc
Introduction to Metadata IngestionFind Integration SourceIntegration OptionsDataHub supports bothpush-basedandpull-basedmetadata integration.Push-based integrations allow you to emit metadata directly from your data systems when metadata changes, while pull-based integrations allow you to "crawl" or "ingest" metadata from the data systems by connecting to them and extracting metadata in a batch or incremental-batch manner. Supporting both mechanisms means that you can integrate with all your systems in the most flexible way possible.Examples of push-based integrations includeAirflow,Spark,Great ExpectationsandProtobuf Schemas. This allows you to get low-latency metadata integration from the "active" agents in your data ecosystem. Examples of pull-based integrations include BigQuery, Snowflake, Looker, Tableau and many others.This document describes the pull-based metadata ingestion system that is built into DataHub for easy integration with a wide variety of sources in your data stack.Getting StartedPrerequisitesBefore running any metadata ingestion job, you should make sure that DataHub backend services are all running. You can either run ingestion via theUIor via theCLI. You can reference the CLI usage guide given there as you go through this page.Core ConceptsSourcesPlease see ourIntegrations pageto browse our ingestion sources and filter on their features.Data systems that we are extracting metadata from are referred to asSources. TheSourcestab on the left in the sidebar shows you all the sources that are available for you to ingest metadata from. For example, we have sources forBigQuery,Looker,Tableauand many others.Metadata Ingestion Source StatusWe apply a Support Status to each Metadata Source to help you understand the integration reliability at a glance.: Certified Sources are well-tested & widely-adopted by the DataHub Community. We expect the integration to be stable with few user-facing issues.: Incubating Sources are ready for DataHub Community adoption but have not been tested for a wide variety of edge-cases. We eagerly solicit feedback from the Community to streghten the connector; minor version changes may arise in future releases.: Testing Sources are available for experiementation by DataHub Community members, but may change without notice.SinksSinks are destinations for metadata. When configuring ingestion for DataHub, you're likely to be sending the metadata to DataHub over either theREST (datahub-sink)or theKafka (datahub-kafka)sink. In some cases, theFilesink is also helpful to store a persistent offline copy of the metadata during debugging.The default sink that most of the ingestion systems and guides assume is thedatahub-restsink, but you should be able to adapt all of them for the other sinks as well!RecipesA recipe is the main configuration file that puts it all together. It tells our ingestion scripts where to pull data from (source) and where to put it (sink).:::tip
Name your recipe with.dhub.yamlextension likemyrecipe.dhub.yamlto use vscode or intellij as a recipe editor with autocomplete
and syntax validation.Make sure yaml plugin is installed for your editor:For vscode installRedhat's yaml pluginFor intellij installofficial yaml plugin:::Sinceacryl-datahubversion>=0.8.33.2, the default sink is assumed to be a DataHub REST endpoint:Hosted at "http://localhost:8080" or the environment variable${DATAHUB_GMS_URL}if presentWith an empty auth token or the environment variable${DATAHUB_GMS_TOKEN}if present.Here's a simple recipe that pulls metadata from MSSQL (source) and puts it into the default sink (datahub rest).# The simplest recipe that pulls metadata from MSSQL and puts it into DataHub# using the Rest API.source:type:mssqlconfig:username:sapassword:${MSSQL_PASSWORD}database:DemoData# sink section omitted as we want to use the default datahub-rest sinkRunning this recipe is as simple as:datahubingest-crecipe.dhub.yamlor if you want to override the default endpoints, you can provide the environment variables as part of the command like below:DATAHUB_GMS_URL="https://my-datahub-server:8080"DATAHUB_GMS_TOKEN="my-datahub-token"datahubingest-crecipe.dhub.yamlA number of recipes are included in theexamples/recipesdirectory. For full info and context on each source and sink, see the pages described in thetable of plugins.Note that one recipe file can only have 1 source and 1 sink. If you want multiple sources then you will need multiple recipe files.Handling sensitive information in recipesWe automatically expand environment variables in the config (e.g.${MSSQL_PASSWORD}),
similar to variable substitution in GNU bash or in docker-compose files. For details, seehttps://docs.docker.com/compose/compose-file/compose-file-v2/#variable-substitution. This environment variable substitution should be used to mask sensitive information in recipe files. As long as you can get env variables securely to the ingestion process there would not be any need to store sensitive information in recipes.Basic Usage of CLI for ingestionpipinstall'acryl-datahub[datahub-rest]'# install the required plugindatahubingest-c./examples/recipes/mssql_to_datahub.dhub.ymlThe--dry-runoption of theingestcommand performs all of the ingestion steps, except writing to the sink. This is useful to validate that the
ingestion recipe is producing the desired metadata events before ingesting them into datahub.# Dry rundatahubingest-c./examples/recipes/example_to_datahub_rest.dhub.yml--dry-run# Short-formdatahubingest-c./examples/recipes/example_to_datahub_rest.dhub.yml-nThe--previewoption of theingestcommand performs all of the ingestion steps, but limits the processing to only the first 10 workunits produced by the source.
This option helps with quick end-to-end smoke testing of the ingestion recipe.# Previewdatahubingest-c./examples/recipes/example_to_datahub_rest.dhub.yml--preview# Preview with dry-rundatahubingest-c./examples/recipes/example_to_datahub_rest.dhub.yml-n--previewBy default--previewcreates 10 workunits. But if you wish to try producing more workunits you can use another option--preview-workunits# Preview 20 workunits without sending anything to sinkdatahubingest-c./examples/recipes/example_to_datahub_rest.dhub.yml-n--preview--preview-workunits=20ReportingBy default, the cli sends an ingestion report to DataHub, which allows you to see the result of all cli-based ingestion in the UI. This can be turned off with the--no-default-reportflag.# Running ingestion with reporting to DataHub turned offdatahubingest-c./examples/recipes/example_to_datahub_rest.dhub.yaml--no-default-reportThe reports include the recipe that was used for ingestion. This can be turned off by adding an additional section to the ingestion recipe.source:# source configssink:# sink configs# Add configuration for the datahub reporterreporting:-type:datahubconfig:report_recipe:falseTransformationsIf you'd like to modify data before it reaches the ingestion sinks – for instance, adding additional owners or tags – you can use a transformer to write your own module and integrate it with DataHub. Transformers require extending the recipe with a new section to describe the transformers that you want to run.For example, a pipeline that ingests metadata from MSSQL and applies a default "important" tag to all datasets is described below:# A recipe to ingest metadata from MSSQL and apply default tags to all tablessource:type:mssqlconfig:username:sapassword:${MSSQL_PASSWORD}database:DemoDatatransformers:# an array of transformers applied sequentially-type:simple_add_dataset_tagsconfig:tag_urns:-"urn:li:tag:Important"# default sink, no config neededCheck out thetransformers guideto learn more about how you can create really flexible pipelines for processing metadata using Transformers!Using as a library (SDK)In some cases, you might want to construct Metadata events directly and use programmatic ways to emit that metadata to DataHub. In this case, take a look at thePython emitterand theJava emitterlibraries which can be called from your own code.Programmatic PipelineIn some cases, you might want to configure and run a pipeline entirely from within your custom Python script. Here is an example of how to do it.programmatic_pipeline.py- a basic mysql to REST programmatic pipeline.DevelopingSee the guides ondeveloping,adding a sourceandusing transformers.CompatibilityDataHub server uses a 3 digit versioning scheme, while the CLI uses a 4 digit scheme. For example, if you're using DataHub server version 0.10.0, you should use CLI version 0.10.0.x, where x is a patch version.
We do this because we do CLI releases at a much higher frequency than server releases, usually every few days vs twice a month.For ingestion sources, any breaking changes will be highlighted in therelease notes. When fields are deprecated or otherwise changed, we will try to maintain backwards compatibility for two server releases, which is about 4-6 weeks. The CLI will also print warnings whenever deprecated options are used.