{"id":2093,"library":"lance-namespace","title":"Lance Namespace","description":"Lance Namespace is an open specification for describing access and operations against a collection of tables in a multimodal lakehouse, providing a unified model for metadata services and compute engines. The `lance-namespace` Python package offers the core interface and a plugin registry, enabling seamless integration with existing data lakehouse infrastructure, Apache Spark, Ray, and LanceDB for AI and analytics workloads. It is currently at version 0.6.1 and sees active development with frequent releases.","status":"active","version":"0.6.1","language":"en","source_language":"en","source_url":"https://github.com/lance-format/lance-namespace","tags":["data-lakehouse","vector-database","metadata","data-format","lakehouse"],"install":[{"cmd":"pip install lance-namespace","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required for OpenAPI-generated client models and operations.","package":"lance-namespace-urllib3-client"},{"reason":"Required for native implementations and full functionality, especially when connecting to local or cloud storage-based namespaces.","package":"lance","optional":true},{"reason":"Often used for data manipulation and compatibility with Lance's Apache Arrow foundation.","package":"pyarrow","optional":true}],"imports":[{"note":"The `connect` factory function is the primary entry point for creating namespace instances.","symbol":"connect","correct":"import lance_namespace\nns = lance_namespace.connect(...)"}],"quickstart":{"code":"import lance_namespace\nimport os\n\n# Configure a root path for the directory-based namespace\n# For persistent storage, change this to a desired directory or cloud path (e.g., s3://my-bucket/data)\nroot_path = os.environ.get('LANCE_ROOT_PATH', '/tmp/lance_namespace_data')\n\n# Connect to a directory-based namespace\n# This creates a namespace instance that manages tables within the specified directory\ntry:\n    ns = lance_namespace.connect(\"dir\", {\"root\": root_path})\n    print(f\"Successfully connected to Lance Namespace at: {root_path}\")\n\n    # Example: List tables (initially empty or existing tables)\n    tables = ns.list_tables()\n    print(f\"Tables in namespace: {tables}\")\n\n    # In a real scenario, you would then use `ns` to declare, create, or manage Lance tables.\n    # For instance, to declare a new table (requires `lance` package for actual data operations):\n    # from lance.client import Client\n    # client = Client(f\"file://{root_path}\")\n    # table_name = \"my_example_table\"\n    # try:\n    #     table_uri = ns.declare_table(table_name, \"table_uri_placeholder\")\n    #     print(f\"Declared table '{table_name}' with URI: {table_uri}\")\n    # except Exception as e:\n    #     print(f\"Could not declare table '{table_name}': {e}\")\n\nexcept Exception as e:\n    print(f\"Error connecting to Lance Namespace: {e}\")\n    print(\"Ensure the 'lance' package is installed for native implementations and required dependencies are met.\")\n\n# Clean up the temporary directory if it was created\n# import shutil\n# if root_path.startswith('/tmp/') and os.path.exists(root_path):\n#     shutil.rmtree(root_path)\n#     print(f\"Cleaned up temporary directory: {root_path}\")","lang":"python","description":"This quickstart demonstrates how to connect to a Lance Namespace using a directory-based implementation. It initializes a `LanceNamespace` instance and lists existing tables. For actual table declaration or data operations, the core `lance` Python package is typically required."},"warnings":[{"fix":"Review the migration guides for the `lance` library for specific breaking changes in namespace-related APIs. Update code to use the latest `lance-namespace` and `lance` API patterns, paying attention to how tables are declared or managed.","message":"The underlying `lance` core library, which `lance-namespace` integrates with, has undergone API cleanups related to namespace handling (e.g., in `lance` 0.6.x). While `lance-namespace` aims for stability, deep integrations might be affected by these changes, especially when upgrading `lance` itself.","severity":"breaking","affected_versions":"0.6.x and potentially older versions of `lance` when integrating."},{"fix":"Always refer to the latest documentation and release notes for the specific version of `lance-namespace` being used. Ensure that code explicitly handles newly introduced features and parameters if applicable, and test thoroughly after upgrades.","message":"The API is actively evolving with significant new features such as `BatchCommitTables`, `table version operations`, `async client support`, `partition specs`, and `vended credentials` being introduced in recent minor releases (0.4.x - 0.6.x). This rapid evolution can lead to code written for older versions encountering unexpected behavior or requiring updates to leverage new capabilities.","severity":"gotcha","affected_versions":"0.4.x - 0.6.x"},{"fix":"Ensure both `lance-namespace` and `lance` are installed: `pip install lance-namespace lance`. Check the specific connector's documentation for any additional requirements.","message":"While `lance-namespace` provides the interface, full functionality, especially for native implementations (like directory-based or cloud storage namespaces), often requires the `lance` package (the core Lance data format library) to be installed alongside it. Missing `lance` can lead to errors or limited functionality during connection or table operations.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For production or complex use cases, transition to Directory Namespace V2 (Manifest-based) or other supported catalog specifications that offer more robust metadata management. Consult the Lance Namespace documentation for V2 configuration details.","message":"The Directory Namespace has two major spec versions: V1 (Directory Listing) and V2 (Manifest). V1 is a simple 1-level namespace suitable for quick starts, while V2 is more advanced, backed by a manifest table, supporting nested namespaces and better performance at scale. Relying on V1 for complex or large-scale deployments may lead to limitations.","severity":"deprecated","affected_versions":"All versions supporting Directory Namespace V1"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}