本页尚未翻译

本页内容仍为英文原文，源自官方文档 management/database。中文翻译正在分批进行中。

Database

Connect to LanceDB and configure storage, credentials and read consistency.

Applies to: Embedded ✅, Enterprise ✅

A database connection provides access to tables and namespaces in a catalog. Use it to create and open tables, list catalog objects, and configure how your application reaches the data.

Connection URIs

URI	Offering	Where queries run
./.lancedb	LanceDB Embedded, with local storage	In your application
s3://bucket/path, gs://bucket/path, az://container/path	LanceDB Embedded, with object storage	In your application
db://my-database	LanceDB Enterprise	On the Enterprise service

Connect to LanceDB has examples for each connection type. A connection to object storage still uses the embedded library: your process reads and writes the bucket directly. Enterprise runs operations remotely and manages the supporting compute and maintenance.

Connect to Enterprise

Replace the placeholders with the database URI, key, region and endpoint provided by your administrator.

import lancedb

db = lancedb.connect(
    uri="db://your-database",
    api_key="your-api-key",
    region="us-east-1",
    host_override="https://your-endpoint",
    sql_host_override="grpc+tls://your-sql-endpoint:10026",
)

import * as lancedb from "@lancedb/lancedb";

const db = await lancedb.connect("db://your-database", {
  apiKey: "your-api-key",
  region: "us-east-1",
  hostOverride: "https://your-endpoint",
});

Python option	TypeScript option	Purpose
api_key	apiKey	Authenticate the connection
region	region	Select the database's region
host_override	hostOverride	Set the Enterprise endpoint
client_config	clientConfig	Configure retries, timeouts and connection pooling. A retry can repeat an append.

Use your deployment's region rather than relying on the us-east-1 default. For application code, load credentials from environment variables or a secrets manager. See Authentication for OAuth and SQL for the separate SQL connection settings.

Storage options

For LanceDB Embedded tables in object storage, storage_options configures credentials, endpoints and options for new tables. This example enables stable row IDs for tables created through the connection:

db = lancedb.connect(
    "s3://bucket/path",
    storage_options={"new_table_enable_stable_row_ids": "true"},
)

import * as lancedb from "@lancedb/lancedb";

const db = await lancedb.connect("s3://bucket/path", {
  storageOptions: { new_table_enable_stable_row_ids: "true" },
});

Set stable row IDs before creating a table that needs them, such as an ordinary materialized-view source in Python SDK 0.40.0. The option does not change tables that already exist. Enterprise storage settings are managed on the server.

See Object storage for provider credentials and other options.

Read consistency

For LanceDB Embedded connections, read_consistency_interval controls how often reads check for table versions committed by other writers. For example, check at most once every five seconds:

from datetime import timedelta
db = lancedb.connect(
    "./.lancedb", read_consistency_interval=timedelta(seconds=5)
)

import * as lancedb from "@lancedb/lancedb";

const db = await lancedb.connect("./.lancedb", { readConsistencyInterval: 5 });

By default, an Embedded table handle does not automatically pick up another process's writes. Reopen the table, check out its latest version, or configure a consistency interval when you need those updates. A zero interval checks on every read, with the cost of a metadata check.

Enterprise manages read freshness on the server. See Consistency for its behavior and the distinction between seeing your own writes and seeing another client's writes.

Database operations

The connection provides methods to create, open, list and drop tables.

Operation	Python	TypeScript
Create a table	create_table	createTable
Open a table	open_table	openTable
List tables	table_names, list_tables	tableNames, listTables
Drop a table	drop_table	dropTable

Use the namespace and pagination options documented in Namespaces when working outside the root namespace or listing a large catalog. Tables covers table schemas, versions and lifecycle operations.

注意

Dropping a table removes its history as well as its current data. You cannot recover a dropped table through table versioning. The LanceDB Embedded drop_database() and drop_all_tables() operations remove all tables without a confirmation prompt.

Async connections

Python's connect_async returns an AsyncConnection. Await its operations when working in an asynchronous application:

db = await lancedb.connect_async("./.lancedb")
table = await db.open_table("documents")

TypeScript's connection and table operations already return promises.

An async connection and a background job serve different purposes. Async APIs let other tasks run while your application waits for an operation. A job represents work that can continue on the server after the submission call returns.

Privileges

A database's OWNERSHIP, USAGE and CREATE_NAMESPACE are granted through the REST ACL API or SQL GRANT/REVOKE:

GRANT USAGE, CREATE SCHEMA ON DATABASE analytics TO ROLE readers

See Privileges for the full statement syntax and every target it reaches.