{"id":8215,"library":"hive-metastore-client","title":"Hive Metastore Client","description":"The `hive-metastore-client` library provides a Pythonic interface for connecting to and performing Data Definition Language (DDL) operations on a Hive Metastore using the Thrift protocol. It simplifies interactions with Hive metadata, enabling users to programmatically create and manage databases, tables, and partitions. Actively maintained by QuintoAndar, the library is currently at version 1.0.9, offering a high-level abstraction over the underlying Thrift APIs.","status":"active","version":"1.0.9","language":"en","source_language":"en","source_url":"https://github.com/quintoandar/hive-metastore-client","tags":["hive","metastore","thrift","ddl","data-management","big-data"],"install":[{"cmd":"pip install hive-metastore-client","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"The library internally relies on Thrift for protocol communication. While the client ships with pre-generated Thrift Python libraries, users who need to regenerate Thrift files or interact at a lower level may require the `thrift` package and compiler.","package":"thrift","optional":true}],"imports":[{"symbol":"HiveMetastoreClient","correct":"from hive_metastore_client import HiveMetastoreClient"},{"symbol":"DatabaseBuilder","correct":"from hive_metastore_client.builders import DatabaseBuilder"},{"symbol":"TableBuilder","correct":"from hive_metastore_client.builders import TableBuilder"}],"quickstart":{"code":"import os\nfrom hive_metastore_client import HiveMetastoreClient\nfrom hive_metastore_client.builders import DatabaseBuilder, FieldSchemaBuilder, TableBuilder\nfrom hive_metastore_client.thrift_files.libraries.thrift_hive_metastore_client.ttypes import Table, FieldSchema, StorageDescriptor, SerDeInfo\n\nHIVE_HOST = os.environ.get('HIVE_METASTORE_HOST', 'localhost')\nHIVE_PORT = int(os.environ.get('HIVE_METASTORE_PORT', '9083'))\n\ntry:\n    # 1. Create a database\n    db_name = \"my_test_database\"\n    database = DatabaseBuilder(name=db_name).build()\n    with HiveMetastoreClient(HIVE_HOST, HIVE_PORT) as hive_client:\n        hive_client.create_database(database, if_not_exists=True)\n        print(f\"Database '{db_name}' created successfully (or already exists).\")\n\n        # 2. Create a table in the new database\n        table_name = \"my_test_table\"\n        columns = [\n            FieldSchemaBuilder(name=\"id\", type=\"int\").build(),\n            FieldSchemaBuilder(name=\"name\", type=\"string\").build()\n        ]\n        table = TableBuilder(name=table_name, database_name=db_name, columns=columns).build()\n        hive_client.create_table(table, if_not_exists=True)\n        print(f\"Table '{db_name}.{table_name}' created successfully (or already exists).\")\n\n        # Example: Get the created table\n        retrieved_table = hive_client.get_table(db_name, table_name)\n        print(f\"Retrieved table: {retrieved_table.name} in database {retrieved_table.dbName}\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    print(\"Ensure HIVE_METASTORE_HOST and HIVE_METASTORE_PORT environment variables are set or defaults are correct.\")\n    print(\"Also, verify that the Hive Metastore service is running and accessible.\")\n","lang":"python","description":"This quickstart demonstrates how to instantiate the HiveMetastoreClient, create a new database, and then create a table within that database. It uses the provided builders for constructing Thrift objects and includes basic error handling for connection issues. Ensure the Hive Metastore service is running and accessible at the specified host and port (defaults to localhost:9083, configurable via environment variables)."},"warnings":[{"fix":"For most users, this library provides pre-generated Thrift interfaces, so manual compilation is not required. If necessary, refer to the library's `thrift_files` directory and documentation for guidance on specific Thrift compiler versions and generation steps.","message":"The client relies on the Thrift protocol. If you attempt to manually compile or regenerate Thrift files (an advanced use case), ensure you use a compatible `thrift` compiler version. The project documentation noted using Thrift 0.14.0 for internal generation. Incompatibilities can lead to cryptic errors if the generated Python code is not consistent with the Metastore server's Thrift definition.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Double-check `HIVE_HOST` and `HIVE_PORT` (or equivalent configuration) values. Ensure the Hive Metastore service is actively running and is reachable from where the Python client is executed. Network firewalls or incorrect DNS resolution can also prevent connections.","message":"Direct connection failures often stem from incorrect Hive Metastore host or port configurations. The `HiveMetastoreClient` requires precise network location of the Metastore service.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Consult the `hive-metastore-client` GitHub issues or documentation for known compatibility limitations with specific Hive Metastore versions. It's generally recommended to test thoroughly when upgrading either the client library or the Hive Metastore server.","message":"Compatibility with the underlying Hive Metastore server version is crucial. While `hive-metastore-client` aims to abstract complexities, major version differences in Hive (e.g., Hive 2.x vs 3.x vs 4.x) can introduce breaking changes in the Metastore's Thrift API. Such changes might affect functionality or lead to unexpected behavior if the client's internal Thrift definitions do not align with the server.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Verify that the Hive Metastore service is running. Check that the `HIVE_METASTORE_HOST` and `HIVE_METASTORE_PORT` (or equivalent) configured in your client code precisely match the running Metastore service. Use network tools (like `ping`, `telnet`, or `nc`) to confirm network reachability from the client machine to the Metastore server on the specified port.","cause":"The Python client failed to establish a network connection to the specified Hive Metastore host and port. This is often due to the Metastore service not running, incorrect host/port, or network/firewall issues.","error":"TTransportException: Could not connect to <HIVE_HOST>:<HIVE_PORT>"},{"fix":"This usually points to an issue on the Hive Metastore server side, not directly the Python client. Check the Hive Metastore server logs for more detailed errors. Common fixes include verifying the `hive-site.xml` configuration (especially `hive.metastore.uris` and database connection details), ensuring the Metastore's backend database is accessible and not overloaded, and restarting the Metastore service.","cause":"This error, typically seen in the Hive Metastore server logs or indirectly reported, indicates a fundamental issue within the Metastore's ability to initialize its internal client, often due to configuration problems, database connectivity, or resource exhaustion (e.g., too many connections to its backend database).","error":"Unable to instantiate org.apache.hadoop.hive.ql.metadata.SessionHiveMetaStoreClient"}]}