## handles.DuckLakeHandle


A DuckLake catalog attached (read-only) in a DuckDB connection.


Usage

``` python
handles.DuckLakeHandle(
    key,
    read_only,
    metadata,
    alias,
    connection,
    snapshot_id,
    attach_sql,
    data_path=None,
    table=None
)
```


The catalog is attached as [alias](handles.DuckLakeHandle.md#tether.handles.DuckLakeHandle.alias) in [connection](handles.DuckLakeHandle.md#tether.handles.DuckLakeHandle.connection), positioned at [snapshot_id](handles.IcebergHandle.md#tether.handles.IcebergHandle.snapshot_id) when opened at a committed state. [attach_sql](handles.DuckLakeHandle.md#tether.handles.DuckLakeHandle.attach_sql) is the exact statement used, for callers that want the same view in their own DuckDB process. Call `close()` when done; a DuckDB-file metadata catalog can only be attached once per process.


## Parameter Attributes


`key: str`  
A short native label for display: the store's URI, path, repository, or database - or, for a branch-addressed system such as Neon, the branch the handle opens. Not an identity: two handles on one store may carry different keys, and the engine never compares handles by it. Use the typed fields ([uri](handles.FileHandle.md#tether.handles.FileHandle.uri), [path](handles.GitHandle.md#tether.handles.GitHandle.path), [branch](handles.NeonHandle.md#tether.handles.NeonHandle.branch), [snapshot_id](handles.IcebergHandle.md#tether.handles.IcebergHandle.snapshot_id), …) for anything that matters.

`read_only: bool`  
Whether writes through this handle are allowed.

`metadata: str`  
The `ducklake:...` metadata connection string.

`alias: str`  
Catalog alias inside [connection](handles.DuckLakeHandle.md#tether.handles.DuckLakeHandle.connection).

`connection: Any`  
A `duckdb.DuckDBPyConnection` with the catalog attached (read-only).

`snapshot_id: int`  
Snapshot the attachment is positioned at.

`attach_sql: str`  
The exact `ATTACH` statement used; reuse it in your own DuckDB.

`data_path: str | None = None`  
`DATA_PATH` passed to `ATTACH`, when set in the locator.

`table: str | None = None`  
Table the locator scopes the handle to (see [table_ref](handles.DuckLakeHandle.md#tether.handles.DuckLakeHandle.table_ref)).


## Methods

| Name | Description |
|----|----|
| [table_ref()](#table_ref) | Qualified table reference (`alias.table`) for SQL. |

------------------------------------------------------------------------


#### table_ref()


Qualified table reference (`alias.table`) for SQL.


Usage

``` python
table_ref(table=None)
```