{"id":4310,"library":"unitycatalog-ai","title":"Unity Catalog AI Python Library","description":"The `unitycatalog-ai` library is the official Python client for integrating with Unity Catalog's AI capabilities, particularly for managing and executing AI functions across various Generative AI tools. It simplifies the creation, registration, and use of Python functions as tools for AI agents, promoting unified governance and access control for data and AI assets. The current version is 0.3.2, with active development and frequent releases.","status":"active","version":"0.3.2","language":"en","source_language":"en","source_url":"https://github.com/unitycatalog/unitycatalog","tags":["AI","Databricks","Unity Catalog","Generative AI","LLM","Data Governance","Machine Learning"],"install":[{"cmd":"pip install unitycatalog-ai","lang":"bash","label":"Install core library"},{"cmd":"pip install unitycatalog-client unitycatalog-ai","lang":"bash","label":"Install with underlying client"}],"dependencies":[{"reason":"Python 3.10 or higher is strongly recommended for simplified type hint processing and full functionality, although >=3.9 is the minimum requirement.","package":"python","optional":false},{"reason":"The `unitycatalog-ai` library is built on top of the `unitycatalog-client` SDK, which provides core asynchronous client functionalities for interacting with Unity Catalog. While often implicitly installed, direct installation ensures all dependencies are met.","package":"unitycatalog-client","optional":false}],"imports":[{"symbol":"UnitycatalogFunctionClient","correct":"from unitycatalog.ai.core.client import UnitycatalogFunctionClient"},{"symbol":"ApiClient","correct":"from unitycatalog.client import ApiClient"},{"symbol":"Configuration","correct":"from unitycatalog.client import Configuration"}],"quickstart":{"code":"import asyncio\nfrom unitycatalog.ai.core.client import UnitycatalogFunctionClient\nfrom unitycatalog.client import ApiClient, Configuration\nimport os\n\n# --- Configuration --- \n# Replace with your Unity Catalog server host or Databricks host\n# For local OSS server, typically 'http://localhost:8080/api/2.1/unity-catalog'\nUC_HOST = os.environ.get('UC_HOST', 'http://localhost:8080/api/2.1/unity-catalog')\n# For Databricks, typically 'https://<your-databricks-instance>/api/2.1/unity-catalog'\n# Ensure you have DBR 16.4+ and serverless compute enabled for Databricks.\n\n# Replace with your Databricks token if connecting to a Databricks-managed UC\nDATABRICKS_TOKEN = os.environ.get('DATABRICKS_TOKEN', 'dapi...') \n\nCATALOG = os.environ.get('UC_CATALOG', 'my_catalog')\nSCHEMA = os.environ.get('UC_SCHEMA', 'my_schema')\n\n# Configure the Unity Catalog API client\nconfig = Configuration(\n    host=UC_HOST,\n    access_token=DATABRICKS_TOKEN if 'databricks.net' in UC_HOST else None\n)\napi_client = ApiClient(configuration=config)\n\n# Use the UnityCatalog client to create an instance of the AI function client\nclient = UnitycatalogFunctionClient(api_client=api_client)\n\n# --- Define a Python function to be registered --- \n# Requirements: type hints for all arguments and return, Google-style docstring.\n# External imports must be within the function body for execution in sandbox mode.\ndef add_numbers(number_1: float, number_2: float) -> float:\n    \"\"\"\n    A function that accepts two floating point numbers, adds them, \n    and returns the resulting sum as a float.\n\n    Args:\n        number_1 (float): The first number.\n        number_2 (float): The second number.\n\n    Returns:\n        float: The sum of the two numbers.\n    \"\"\"\n    return number_1 + number_2\n\nasync def main():\n    try:\n        # Register the Python function in Unity Catalog\n        print(f\"Registering function {CATALOG}.{SCHEMA}.add_numbers...\")\n        created_function = await client.create_python_function(\n            func=add_numbers,\n            catalog=CATALOG,\n            schema=SCHEMA,\n            name=\"add_numbers\",\n            replace=True # Overwrite if already exists\n        )\n        print(f\"Function registered: {created_function.name}\")\n\n        # Execute the registered function\n        print(f\"Executing function {created_function.name}...\")\n        result = await client.execute_function(\n            name=created_function.name,\n            catalog=CATALOG,\n            schema=SCHEMA,\n            parameters={'number_1': 10.5, 'number_2': 20.3}\n        )\n        print(f\"Execution result: {result.result}\")\n\n        # Clean up (optional: delete the function)\n        # print(f\"Deleting function {created_function.name}...\")\n        # await client.delete_function(\n        #     name=created_function.name,\n        #     catalog=CATALOG,\n        #     schema=SCHEMA\n        # )\n        # print(\"Function deleted.\")\n\n    except Exception as e:\n        print(f\"An error occurred: {e}\")\n\nif __name__ == \"__main__\":\n    # The client is async-based, so run in an event loop\n    asyncio.run(main())\n","lang":"python","description":"This quickstart demonstrates how to initialize the `UnitycatalogFunctionClient`, define a Python function with proper type hints and a Google-style docstring, and then register and execute it within Unity Catalog. It includes placeholders for configuring the Unity Catalog host and an optional Databricks token, and shows how to use both `create_python_function` and `execute_function`."},"warnings":[{"fix":"Monitor official documentation and release notes for upcoming changes. Implement robust error handling and regularly test against new library versions.","message":"The APIs for Unity Catalog, and by extension `unitycatalog-ai`, are currently evolving and should not be assumed to be stable. This implies that future versions may introduce breaking changes without a major version bump, requiring code adjustments.","severity":"breaking","affected_versions":"All versions prior to 1.0.0"},{"fix":"Ensure all functions adhere to the specified typing and docstring conventions. Move all external `import` statements into the function body for proper resolution during execution within Unity Catalog's environment.","message":"Python functions registered with Unity Catalog have specific requirements: all arguments and return values must have type hints, and the docstring must follow Google-style guidelines (including descriptions for the function, arguments, and return). Additionally, any non-core Python library imports *must* be defined within the function body itself, not globally.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Be mindful of these restrictions when designing functions. Avoid operations that require blocked modules or excessive resources. If such operations are critical, investigate alternative approaches or consider whether Unity Catalog functions are the appropriate solution for that specific task.","message":"Unity Catalog functions, particularly from version 0.3.0+, run by default in a 'sandbox' execution mode. This mode isolates code execution for security but imposes CPU/memory limits and blocks access to certain system modules (e.g., `sys`, `subprocess`, `ctypes`, `socket`, `importlib`, `pickle`, `marshall`, `shutil`).","severity":"gotcha","affected_versions":">=0.3.0"},{"fix":"If working in an environment with a running event loop, use existing event loops (e.g., `asyncio.run()` once at the top level or `await` directly in a running async context). Utilize the synchronous versions of `unitycatalog-ai` methods if simpler interfaces are preferred or async complexities need to be avoided.","message":"The `unitycatalog-client` SDK, which `unitycatalog-ai` builds upon, is asynchronous (aiohttp-based). While `unitycatalog-ai` provides synchronous wrappers, direct asynchronous calls require careful management of the event loop. In environments like Jupyter Notebooks, attempting to create additional event loops for async method calls can lead to errors.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Before using the library, ensure a Unity Catalog server is installed, configured, and accessible. For a local open-source setup, Java 17+ is a prerequisite for running the server.","message":"The `unitycatalog-ai` library requires a running Unity Catalog server (either a local open-source instance or a Databricks-managed service) to function. The Python library itself does not provide the server.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}