{"id":1603,"library":"openlineage-integration-common","title":"OpenLineage Integration Common Library","description":"The `openlineage-integration-common` library provides shared data models, utilities, and provider interfaces for building OpenLineage integrations in Python. It is a foundational component often used by other OpenLineage libraries (like `openlineage-python`) and custom integrations. The current version is 1.46.0, and it follows a frequent release cadence, often updated alongside the main OpenLineage project.","status":"active","version":"1.46.0","language":"python","source_language":"en","source_url":"https://github.com/OpenLineage/OpenLineage/tree/main/integration/common","tags":["lineage","data-governance","metadata","etl","data-pipeline","integrations"],"install":[{"cmd":"pip install openlineage-integration-common","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Used for defining data models and schema validation.","package":"pydantic","optional":false},{"reason":"Used for YAML configuration parsing.","package":"PyYAML","optional":false}],"imports":[{"note":"A common model for representing database table schemas.","symbol":"DbTableSchema","correct":"from openlineage.common.models import DbTableSchema"},{"note":"Used for parsing and representing SQL statements within integrations.","symbol":"SQLStatement","correct":"from openlineage.common.provider import SQLStatement"},{"note":"Utility to retrieve common OpenLineage configuration.","symbol":"get_common_config","correct":"from openlineage.common.config import get_common_config"},{"note":"Model for representing data sources.","symbol":"Source","correct":"from openlineage.common.models import Source"}],"quickstart":{"code":"from openlineage.common.models import DbTableSchema, Source\nfrom openlineage.common.provider import SQLStatement\n\n# Example: Defining a database table schema\ndb_table = DbTableSchema(\n    schema='public',\n    table='my_table',\n    fields=[\n        {'name': 'id', 'type': 'int'},\n        {'name': 'name', 'type': 'string'}\n    ]\n)\nprint(f\"Defined DB Table: {db_table.json(indent=2)}\")\n\n# Example: Defining a data source\nmy_source = Source(scheme='postgresql', authority='localhost:5432', connection_url='jdbc:postgresql://localhost:5432/mydb')\nprint(f\"Defined Source: {my_source.json(indent=2)}\")\n\n# Example: Representing a SQL statement (without actual parsing logic)\nsql_statement = SQLStatement(query='SELECT * FROM public.my_table')\nprint(f\"SQL Statement: {sql_statement.json(indent=2)}\")","lang":"python","description":"This quickstart demonstrates how to use fundamental data models like `DbTableSchema`, `Source`, and `SQLStatement` provided by `openlineage-integration-common`. These models are essential building blocks when developing custom OpenLineage integrations or working with parsed metadata."},"warnings":[{"fix":"Upgrade to `openlineage-integration-common` version 1.40.1 or newer to restore `__version__` variables.","message":"Version 1.40.0 experienced a breaking change where `__version__` variables were missing in top-level modules, which could affect tools relying on programmatic version checks.","severity":"breaking","affected_versions":"1.40.0"},{"fix":"For sending OpenLineage events to a collector, use the `openlineage-python` library and its `OpenLineageClient`. `openlineage-python` internally depends on `openlineage-integration-common`.","message":"This library (`openlineage-integration-common`) provides common models and utilities primarily for *building* OpenLineage integrations, or as an internal dependency. It is NOT the primary client library for sending OpenLineage events.","severity":"gotcha","affected_versions":"All versions"},{"fix":"When working with OpenLineage Facets, ensure you are importing from `openlineage.client.facet` (after installing `openlineage-python`), rather than searching exclusively within `openlineage.common`.","message":"Many core OpenLineage 'Facet' definitions (e.g., `SchemaDatasetFacet`, `RunFacet`) are located in the `openlineage.client.facet` module, which is part of the `openlineage-python` package, not directly in `openlineage.common`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'1.46.0':47 'alongsid':57 'build':20 'cadenc':54 'common':3,9 'compon':29 'current':44 'custom':41 'data':13,64,69 'data-govern':63 'data-pipelin':68 'etl':67 'follow':50 'foundat':28 'frequent':52 'govern':65 'integr':2,8,22,42,71 'interfac':18 'librari':4,10,35 'like':36 'lineag':62 'main':59 'metadata':66 'model':14 'often':30,55 'openlineag':1,7,21,34,38,60 'openlineage-integration-common':6 'openlineage-python':37 'pipelin':70 'project':61 'provid':11,17 'python':24,39 'releas':53 'share':12 'updat':56 'use':31 'util':15 'version':45","created_at":"2026-04-09T03:55:13.404618+00:00","updated_at":"2026-04-16T17:36:24.505023+00:00","problems":[{"fix":"Ensure the package is installed: `pip install openlineage-integration-common`","cause":"The `openlineage-integration-common` package is not installed in the Python environment, or a module from it is being imported incorrectly or from a location not on the Python path.","error":"ModuleNotFoundError: No module named 'openlineage.common'"},{"fix":"Verify that Airflow connections are correctly configured and accessible to the OpenLineage extractor. This might involve configuring Airflow's secrets backend or ensuring connection details are explicitly provided if the extractor cannot resolve them automatically.","cause":"This error typically occurs within an OpenLineage Airflow extractor when it attempts to access connection details (like host or port) from an Airflow connection object that is `None` or not properly resolved, often because connection information is stored in a secrets backend that the extractor cannot access.","error":"AttributeError: 'NoneType' object has no attribute 'host'"},{"fix":"Set the required environment variables (e.g., `OPENLINEAGE_URL=http://localhost:5000 OPENLINEAGE_NAMESPACE=default`) or provide a valid `openlineage.yml` configuration file in a discoverable location.","cause":"The OpenLineage client or an integration (like the Airflow provider) cannot find essential configuration parameters, such as the OpenLineage backend URL (`OPENLINEAGE_URL`) or namespace (`OPENLINEAGE_NAMESPACE`), preventing it from emitting events.","error":"ValueError: OpenLineage is missing configuration, please refer to the OL setup docs."},{"fix":"Verify that the `OPENLINEAGE_EXTRACTORS` environment variable points to a correct and importable path from the Airflow worker's Python environment. Additionally, ensure custom extractor code avoids top-level Airflow imports by placing them within methods or guarding them with `typing.TYPE_CHECKING` to prevent circular dependencies.","cause":"Airflow's scheduler or triggerer processes are unable to correctly import or load custom OpenLineage extractors. This is often due to an incorrect path specified in the `OPENLINEAGE_EXTRACTORS` environment variable, or issues like circular imports within the custom extractor code that prevent successful loading.","error":"The Airflow Scheduler and Airflow Triggerer are failing to load the openlineage plugin with Custom extractors"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.52.0","cli_name":"","cli_version":null,"type":"library","homepage":"https://openlineage.io/","github":"https://github.com/OpenLineage/OpenLineage","docs":null,"changelog":null,"pypi":"https://pypi.org/project/openlineage-integration-common/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["observability","data","devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-27","next_check":"2026-07-28","install_tag":null}}