---
warning: DO NOT CHANGE THIS MANUALLY, THIS IS GENERATED BY https://github.com/duckdb/community-extensions repository, check README there
title: hive_metastore
excerpt: |
  DuckDB Community Extensions
  Attach Apache Hive Metastore as a native DuckDB catalog and read/write the data inside with ease!

extension:
  name: hive_metastore
  description: Attach Apache Hive Metastore as a native DuckDB catalog and read/write the data inside with ease!
  version: 0.2.0
  language: C++
  build: cmake
  license: MIT
  excluded_platforms: "wasm_mvp;wasm_eh;wasm_threads;windows_amd64_mingw;windows_amd64;windows_arm64"
  vcpkg_commit: "84bab45d415d22042bd0b9081aea57f362da3f35"
  requires_toolchains: "parser_tools"
  maintainers:
    - ilum-cloud
    - thijs-s

repo:
  github: ilum-cloud/duckdb-hive-metastore
  next: 358bab899039c5934507aee66c67df3d37671ce0
  ref: 182aea05140728a50cddc79eecce3399617da1ce
  andium: 60f4912c75f86a89f98e28925bad7159415641cb

docs:
  hello_world: |
    -- Attach the Hive Metastore as a catalog in DuckDB
    ATTACH 'thrift://<host>:<port>' AS <catalog_name> (TYPE hive_metastore);

    -- Query any HMS table as if it were native DuckDB
    SELECT * FROM <catalog_name>.<schema_name>.<table_name>;

    -- For object-storage-backed tables, configure storage secrets as usual
    CREATE SECRET s3 (TYPE S3, KEY_ID 'access-key', SECRET 'secret-key', ENDPOINT 'localhost:9000');

    -- Create a managed table (requires WAREHOUSE_LOCATION on ATTACH)
    ATTACH 'thrift://localhost:9083' AS hms (TYPE hive_metastore, WAREHOUSE_LOCATION 's3a://my-bucket/warehouse');
    CREATE TABLE hms.default.events (id INT, ts TIMESTAMP, payload VARCHAR);
    INSERT INTO hms.default.events VALUES (1, NOW(), 'hello');
  extended_description: |
    The DuckDB Hive Metastore extension connects DuckDB to an Apache Hive Metastore over the Thrift protocol and
    exposes HMS databases and tables as a first-class DuckDB catalog.
    Reads, writes, and table creation are all implemented natively,
    with DuckDB's format scanners handling the underlying data files.

    ## Supported table formats

    | Format       | SELECT   | INSERT                | CTAS | CREATE TABLE         |
    |--------------|----------|-----------------------|------|----------------------|
    | Parquet      | yes      | yes (non-partitioned) | yes  | yes                  |
    | CSV / Text   | yes      | yes (non-partitioned) | yes  | yes                  |
    | Delta Lake   | yes      | via `delta` extension | no   | no                   |
    | Iceberg      | yes¹     | no                    | no   | no                   |
    | Avro         | yes      | no (read-only)        | no   | metastore entry only |
    | ORC          | partial² | no                    | no   | partial²             |

    ¹ Iceberg tables created by Spark may require `unsafe_enable_version_guessing = true`.
    ² ORC support depends on DuckDB's underlying ORC scanner.

    UPDATE, DELETE, and `COPY TO` against HMS tables are not supported - this matches Hive's append-only semantics.

    ## Key capabilities

    - Direct Thrift communication with the metastore - no REST catalog or Hadoop classpath needed
    - Automatic format detection from HMS `inputFormat` / `outputFormat` / SerDe metadata
    - Schema and database discovery, including complex types (struct, array, map) from Spark-created tables
    - Hive-style partitioning automatically applied at scan time
    - S3-compatible object storage (AWS S3, MinIO, etc.) via DuckDB's `httpfs`
    - Path normalization for Alibaba OSS (`oss://`), Tencent COS (`cos://`, `cosn://`) - rewritten to `s3://` so any S3-compatible secret works
    - Avro logical-type handling: `date`, `timestamp-micros`, and `decimal` round-trip with correct SQL types
    - INSERT and CTAS write a single `data_<uuid>.<ext>` file per statement to the table's `LOCATION`; concurrent writers do not collide
    - CREATE TABLE creates managed (`MANAGED_TABLE`) or external (`EXTERNAL_TABLE`) entries with proper Hive type strings, interoperable with Spark and Trino readers

    ## Attaching a metastore

    ```sql
    ATTACH 'thrift://<host>:<port>' AS <catalog_name> (<options>);
    ```

    Options:

    - `TYPE` (required) - must be `hive_metastore`
    - `WAREHOUSE_LOCATION` - default base path for managed tables created via `CREATE TABLE` without an explicit `LOCATION`. When set, managed tables land at `<warehouse>/<db>/<table>`.
    - `DEFAULT_SCHEMA` - schema used when a query omits the schema name. Defaults to `default`.

    ## Creating tables

    ```sql
    ATTACH 'thrift://localhost:9083' AS hms
      (TYPE hive_metastore, WAREHOUSE_LOCATION 's3a://my-bucket/warehouse');

    -- Managed Parquet table (default format)
    CREATE TABLE hms.default.sales (id INT, amount DECIMAL(10,2), region VARCHAR);

    -- External table with explicit format and location
    CREATE TABLE hms.default.events (id INT, ts TIMESTAMP)
      WITH (location='s3a://my-bucket/events', format='parquet');

    -- Avro: metastore entry only, written by Spark/Hive
    CREATE TABLE hms.default.shipments (id INT, ship_date DATE)
      WITH (location='s3a://my-bucket/shipments', format='avro');
    ```

    Format and location are passed via standard SQL `WITH (...)` tags.
    If neither `LOCATION` nor `WAREHOUSE_LOCATION` is available, `CREATE TABLE` fails with a clear error.

    ## Reading Delta, Iceberg, and Avro

    The extension delegates data reads to DuckDB's format scanners.
    Install and load the relevant extension before querying:

    ```sql
    INSTALL delta;    LOAD delta;
    INSTALL iceberg;  LOAD iceberg;
    INSTALL avro;     LOAD avro;
    ```

    Object-storage credentials use the standard DuckDB `CREATE SECRET` flow:

    ```sql
    CREATE SECRET s3 (
      TYPE S3,
      KEY_ID 'access-key',
      SECRET 'secret-key',
      ENDPOINT 's3.amazonaws.com'
    );
    ```

extension_star_count: 5
extension_star_count_pretty: 5
extension_download_count: 12862
extension_download_count_pretty: 12.9k
image: '/images/community_extensions/social_preview/preview_community_extension_hive_metastore.png'
layout: community_extension_doc
---
### Compatibility Matrix

This table covers all DuckDB releases that have not reached [end-of-life](https://duckdb.org/release_calendar), including LTS releases, and shows the 2 most recent patch releases of each. Older patch releases are not listed, but the extension may be available for them as well.

<div class="extension_compatibility_table"></div>

| Platform | 1.4.4 | 1.4.5 | 1.5.5 | 1.5.6 | 2.0.0 |
| :--- | :---: | :---: | :---: | :---: | :---: |
| Linux AMD64 | ✅ | ❌ | ✅ | ✅ | ❌ |
| Linux ARM64 | ✅ | ❌ | ✅ | ✅ | ❌ |
| macOS AMD64 | ✅ | ❌ | ✅ | ✅ | ❌ |
| macOS ARM64 | ✅ | ❌ | ✅ | ✅ | ❌ |
| Windows AMD64 | ❌ | ❌ | ❌ | ❌ | ❌ |
| Windows ARM64 | ❌ | ❌ | ❌ | ❌ | ❌ |
| WebAssembly | ❌ | ❌ | ❌ | ❌ | ❌ |

### Installing and Loading
```sql
INSTALL {{ page.extension.name }} FROM community;
LOAD {{ page.extension.name }};
```

{% if page.docs.hello_world %}
### Example
```sql
{{ page.docs.hello_world }}```
{% endif %}

{% if page.docs.extended_description %}
### About {{ page.extension.name }}
{{ page.docs.extended_description }}
{% endif %}
### Added Functions

<div class="extension_functions_table"></div>

This extension does not add any functions.

### Overloaded Functions

<div class="extension_functions_table"></div>

This extension does not add any function overloads.

### Added Types

<div class="extension_types_table"></div>

This extension does not add any types.

### Added Settings

<div class="extension_settings_table"></div>

This extension does not add any settings.