mirror of
https://github.com/lancedb/lancedb.git
synced 2026-10-13 07:12:27 +00:00
Jack Ye
44f4b959ca
The tab opened on Quickstart, buried "What is LanceDB?" inside it, and put everything else under a single Guides group that had to be expanded before any section was reachable. Model training sat outside it for no reason. Reorganize around what a user does, in order: Introduction, Catalog, Ingestion, Search, Feature engineering, Training, Maintenance, SQL. Guides is gone as a level, so each section is one click. New pages: catalog overview and database, and a compaction page under Maintenance. tables/update covered four separate operations, so it becomes the Ingestion section — insert, merge insert, update, delete — with insert drawing on the large-dataset material from tables/create. Its old URL redirects. Agentic skills move to their own tab after API Reference.
95 lines
3.0 KiB
Plaintext
95 lines
3.0 KiB
Plaintext
---
|
|
title: "Database"
|
|
sidebarTitle: "Database"
|
|
description: "The root of a catalog. Connecting to one, and the operations it holds."
|
|
icon: database
|
|
---
|
|
|
|
A database is the root of a catalog. A connection opens exactly one, and every
|
|
other object is reached through it.
|
|
|
|
## Connecting {#connecting}
|
|
|
|
```python
|
|
import lancedb
|
|
|
|
db = lancedb.connect("./.lancedb") # a local directory
|
|
db = lancedb.connect("s3://bucket/path") # object storage
|
|
db = lancedb.connect("db://my-database", api_key="...") # Cloud or Enterprise
|
|
```
|
|
|
|
The URI decides what kind of database you get, and that decision reaches
|
|
further than it looks. A local or object-store URI opens the data directly from
|
|
your process. A `db://` URI talks to a deployment, which is what makes
|
|
server-side execution — [functions](/feature-engineering/functions), remote refreshes,
|
|
[SQL](/sql) — available, and what makes a few local-only features unavailable.
|
|
|
|
`connect_async` returns an `AsyncConnection` with the same surface as
|
|
coroutines.
|
|
|
|
### Storage options {#storage-options}
|
|
|
|
`storage_options` configures the underlying store — credentials, endpoints, and
|
|
per-table defaults for tables created through this connection:
|
|
|
|
```python
|
|
db = lancedb.connect(
|
|
"s3://bucket/path",
|
|
storage_options={"new_table_enable_stable_row_ids": "true"},
|
|
)
|
|
```
|
|
|
|
<Warning>
|
|
`new_table_enable_stable_row_ids` is worth setting deliberately. Stable row ids
|
|
cannot be enabled after a table exists, and a
|
|
[materialized view](/feature-engineering/materialized-views) requires its source to have
|
|
them. A table created without them cannot later become a view's source without
|
|
being recreated.
|
|
</Warning>
|
|
|
|
See [Storage](/storage) for the full set.
|
|
|
|
## Operations {#operations}
|
|
|
|
| | |
|
|
| --- | --- |
|
|
| `db.table_names()` | list the tables in the database |
|
|
| `db.create_table(name, data)` | create a table — see [Table](/tables) |
|
|
| `db.open_table(name)` | open an existing table |
|
|
| `db.drop_table(name)` | drop one table |
|
|
| `db.drop_database()` | drop everything in the database |
|
|
|
|
Each accepts `namespace_path` to act inside a [namespace](/namespaces)
|
|
rather than at the root.
|
|
|
|
```python
|
|
db.table_names()
|
|
tbl = db.open_table("documents")
|
|
db.drop_table("documents")
|
|
```
|
|
|
|
<Warning>
|
|
`drop_database()` removes every table in the database. There is no confirmation
|
|
and no undo — table [versioning](/tables/versioning) does not survive the
|
|
table being dropped.
|
|
</Warning>
|
|
|
|
## Read consistency {#consistency}
|
|
|
|
`read_consistency_interval` controls how often a connection checks for versions
|
|
committed by other writers. The default reads a snapshot taken when the table
|
|
was opened, so a long-lived connection will not see other processes' writes
|
|
until it reopens.
|
|
|
|
Set it when several processes write the same table and readers must observe
|
|
those writes:
|
|
|
|
```python
|
|
from datetime import timedelta
|
|
|
|
db = lancedb.connect(uri, read_consistency_interval=timedelta(seconds=5))
|
|
```
|
|
|
|
The cost is a metadata check on that interval. See
|
|
[Consistency](/tables/consistency).
|