配置¶

Spark DSV2 目录通过 Lance Namespace 与 Lance 集成。

基本设置¶

通过设置适当的 Spark 目录实现和命名空间特定选项，使用 LanceNamespaceSparkCatalog 配置 Spark

参数	类型	必需	描述
`spark.sql.catalog.{name}`	字符串	✓	设置为 `com.lancedb.lance.spark.LanceNamespaceSparkCatalog`
`spark.sql.catalog.{name}.impl`	字符串	✓	命名空间实现，短名称如 `dir`、`rest`、`hive3`、`glue` 或完整的 Java 实现类

命名空间实现示例¶

目录命名空间¶

ScalaJavaSpark ShellSpark Submit

import org.apache.spark.sql.SparkSession

val spark = SparkSession.builder()
    .appName("lance-dir-example")
    .config("spark.sql.catalog.lance", "com.lancedb.lance.spark.LanceNamespaceSparkCatalog")
    .config("spark.sql.catalog.lance.impl", "dir")
    .config("spark.sql.catalog.lance.root", "/path/to/lance/database")
    .getOrCreate()

import org.apache.spark.sql.SparkSession;

SparkSession spark = SparkSession.builder()
    .appName("lance-dir-example")
    .config("spark.sql.catalog.lance", "com.lancedb.lance.spark.LanceNamespaceSparkCatalog")
    .config("spark.sql.catalog.lance.impl", "dir")
    .config("spark.sql.catalog.lance.root", "/path/to/lance/database")
    .getOrCreate();

spark-shell \
  --packages com.lancedb:lance-spark-bundle-3.5_2.12:0.0.7 \
  --conf spark.sql.catalog.lance=com.lancedb.lance.spark.LanceNamespaceSparkCatalog \
  --conf spark.sql.catalog.lance.impl=dir \
  --conf spark.sql.catalog.lance.root=/path/to/lance/database

spark-submit \
  --packages com.lancedb:lance-spark-bundle-3.5_2.12:0.0.7 \
  --conf spark.sql.catalog.lance=com.lancedb.lance.spark.LanceNamespaceSparkCatalog \
  --conf spark.sql.catalog.lance.impl=dir \
  --conf spark.sql.catalog.lance.root=/path/to/lance/database \
  your-application.jar

目录配置参数¶

参数	必需	描述
`spark.sql.catalog.{name}.root`	✗	存储根位置（默认：当前目录）
`spark.sql.catalog.{name}.storage.*`	✗	其他 OpenDAL 存储配置选项
`spark.sql.catalog.{name}.extra_level`	✗	2 级命名空间的虚拟级别（自动设置为 `default`）。有关详细信息，请参阅关于命名空间级别的说明。

示例设置

本地存储S3MinIO

from pyspark.sql import SparkSession

spark = SparkSession.builder \
    .appName("lance-dir-local-example") \
    .config("spark.sql.catalog.lance", "com.lancedb.lance.spark.LanceNamespaceSparkCatalog") \
    .config("spark.sql.catalog.lance.impl", "dir") \
    .config("spark.sql.catalog.lance.root", "/path/to/lance/database") \
    .getOrCreate()

from pyspark.sql import SparkSession

spark = SparkSession.builder \
    .appName("lance-dir-minio-example") \
    .config("spark.sql.catalog.lance", "com.lancedb.lance.spark.LanceNamespaceSparkCatalog") \
    .config("spark.sql.catalog.lance.impl", "dir") \
    .config("spark.sql.catalog.lance.root", "s3://bucket-name/lance-data") \
    .config("spark.sql.catalog.lance.storage.access_key_id", "abc") \
    .config("spark.sql.catalog.lance.storage.secret_access_key", "def")
    .config("spark.sql.catalog.lance.storage.session_token", "ghi") \
    .getOrCreate()

from pyspark.sql import SparkSession

spark = SparkSession.builder \
    .appName("lance-dir-minio-example") \
    .config("spark.sql.catalog.lance", "com.lancedb.lance.spark.LanceNamespaceSparkCatalog") \
    .config("spark.sql.catalog.lance.impl", "dir") \
    .config("spark.sql.catalog.lance.root", "s3://bucket-name/lance-data") \
    .config("spark.sql.catalog.lance.storage.endpoint", "http://minio:9000") \
    .config("spark.sql.catalog.lance.storage.aws_allow_http", "true") \
    .config("spark.sql.catalog.lance.storage.access_key_id", "admin") \
    .config("spark.sql.catalog.lance.storage.secret_access_key", "password") \
    .getOrCreate()

REST 命名空间¶

这里我们以 LanceDB Cloud 作为 REST 命名空间的示例

PySparkScalaJavaSpark ShellSpark Submit

spark = SparkSession.builder \
    .appName("lance-rest-example") \
    .config("spark.sql.catalog.lance", "com.lancedb.lance.spark.LanceNamespaceSparkCatalog") \
    .config("spark.sql.catalog.lance.impl", "rest") \
    .config("spark.sql.catalog.lance.headers.x-api-key", "your-api-key") \
    .config("spark.sql.catalog.lance.headers.x-lancedb-database", "your-database") \
    .config("spark.sql.catalog.lance.uri", "https://your-database.us-east-1.api.lancedb.com") \
    .getOrCreate()

val spark = SparkSession.builder()
    .appName("lance-rest-example")
    .config("spark.sql.catalog.lance", "com.lancedb.lance.spark.LanceNamespaceSparkCatalog")
    .config("spark.sql.catalog.lance.impl", "rest")
    .config("spark.sql.catalog.lance.headers.x-api-key", "your-api-key")
    .config("spark.sql.catalog.lance.headers.x-lancedb-database", "your-database")
    .config("spark.sql.catalog.lance.uri", "https://your-database.us-east-1.api.lancedb.com")
    .getOrCreate()

SparkSession spark = SparkSession.builder()
    .appName("lance-rest-example")
    .config("spark.sql.catalog.lance", "com.lancedb.lance.spark.LanceNamespaceSparkCatalog")
    .config("spark.sql.catalog.lance.impl", "rest")
    .config("spark.sql.catalog.lance.headers.x-api-key", "your-api-key")
    .config("spark.sql.catalog.lance.headers.x-lancedb-database", "your-database")
    .config("spark.sql.catalog.lance.uri", "https://your-database.us-east-1.api.lancedb.com")
    .getOrCreate();

spark-shell \
  --packages com.lancedb:lance-spark-bundle-3.5_2.12:0.0.7 \
  --conf spark.sql.catalog.lance=com.lancedb.lance.spark.LanceNamespaceSparkCatalog \
  --conf spark.sql.catalog.lance.impl=rest \
  --conf spark.sql.catalog.lance.headers.x-api-key=your-api-key \
  --conf spark.sql.catalog.lance.headers.x-lancedb-database=your-database \
  --conf spark.sql.catalog.lance.uri=https://your-database.us-east-1.api.lancedb.com

spark-submit \
  --packages com.lancedb:lance-spark-bundle-3.5_2.12:0.0.7 \
  --conf spark.sql.catalog.lance=com.lancedb.lance.spark.LanceNamespaceSparkCatalog \
  --conf spark.sql.catalog.lance.impl=rest \
  --conf spark.sql.catalog.lance.headers.x-api-key=your-api-key \
  --conf spark.sql.catalog.lance.headers.x-lancedb-database=your-database \
  --conf spark.sql.catalog.lance.uri=https://your-database.us-east-1.api.lancedb.com \
  your-application.jar

REST 配置参数¶

参数	必需	描述
`spark.sql.catalog.{name}.uri`	✓	REST API 端点 URL（例如，`https://api.lancedb.com`）
`spark.sql.catalog.{name}.headers.*`	✗	用于身份验证的 HTTP 头（例如，`headers.x-api-key`）

AWS Glue 命名空间¶

AWS Glue 是亚马逊的托管元数据存储服务，为您的数据资产提供集中式目录。

PySparkScalaJava

spark = SparkSession.builder \
    .appName("lance-glue-example") \
    .config("spark.sql.catalog.lance", "com.lancedb.lance.spark.LanceNamespaceSparkCatalog") \
    .config("spark.sql.catalog.lance.impl", "glue") \
    .config("spark.sql.catalog.lance.region", "us-east-1") \
    .config("spark.sql.catalog.lance.catalog_id", "123456789012") \
    .config("spark.sql.catalog.lance.access_key_id", "your-access-key") \
    .config("spark.sql.catalog.lance.secret_access_key", "your-secret-key") \
    .config("spark.sql.catalog.lance.root", "s3://your-bucket/lance") \
    .getOrCreate()

val spark = SparkSession.builder()
    .appName("lance-glue-example")
    .config("spark.sql.catalog.lance", "com.lancedb.lance.spark.LanceNamespaceSparkCatalog")
    .config("spark.sql.catalog.lance.impl", "glue")
    .config("spark.sql.catalog.lance.region", "us-east-1")
    .config("spark.sql.catalog.lance.catalog_id", "123456789012")
    .config("spark.sql.catalog.lance.access_key_id", "your-access-key")
    .config("spark.sql.catalog.lance.secret_access_key", "your-secret-key")
    .config("spark.sql.catalog.lance.root", "s3://your-bucket/lance")
    .getOrCreate()

SparkSession spark = SparkSession.builder()
    .appName("lance-glue-example")
    .config("spark.sql.catalog.lance", "com.lancedb.lance.spark.LanceNamespaceSparkCatalog")
    .config("spark.sql.catalog.lance.impl", "glue")
    .config("spark.sql.catalog.lance.region", "us-east-1")
    .config("spark.sql.catalog.lance.catalog_id", "123456789012")
    .config("spark.sql.catalog.lance.access_key_id", "your-access-key")
    .config("spark.sql.catalog.lance.secret_access_key", "your-secret-key")
    .config("spark.sql.catalog.lance.root", "s3://your-bucket/lance")
    .getOrCreate();

额外依赖¶

使用 Glue 命名空间需要主 Lance Spark 捆绑包之外的额外依赖项：- lance-namespace-glue：Lance Glue 命名空间实现 - AWS Glue 相关依赖项：最简单的方法是使用 software.amazon.awssdk:bundle，它包含所有必要的 AWS SDK 组件，但如果需要，您可以指定单个依赖项

Spark Shell 示例

spark-shell \
  --packages com.lancedb:lance-spark-bundle-3.5_2.12:0.0.7,com.lancedb:lance-namespace-glue:0.0.7,software.amazon.awssdk:bundle:2.20.0 \
  --conf spark.sql.catalog.lance=com.lancedb.lance.spark.LanceNamespaceSparkCatalog \
  --conf spark.sql.catalog.lance.impl=glue \
  --conf spark.sql.catalog.lance.root=s3://your-bucket/lance

Glue 配置参数¶

参数	必需	描述
`spark.sql.catalog.{name}.region`	✗	Glue 操作的 AWS 区域（例如，`us-east-1`）。如果未指定，则从默认 AWS 区域链派生
`spark.sql.catalog.{name}.catalog_id`	✗	Glue 目录 ID，默认为调用者的 AWS 账户 ID
`spark.sql.catalog.{name}.endpoint`	✗	用于连接到兼容元数据存储的自定义 Glue 服务端点
`spark.sql.catalog.{name}.access_key_id`	✗	用于静态凭据的 AWS 访问密钥 ID
`spark.sql.catalog.{name}.secret_access_key`	✗	用于静态凭据的 AWS 秘密访问密钥
`spark.sql.catalog.{name}.session_token`	✗	用于临时凭据的 AWS 会话令牌
`spark.sql.catalog.{name}.root`	✗	存储根位置（例如，`s3://bucket/path`），默认为当前目录
`spark.sql.catalog.{name}.storage.*`	✗	其他存储配置选项

Apache Hive 命名空间¶

Lance 支持 Hive 2.x 和 Hive 3.x 元数据存储进行元数据管理。

Hive 3.x 命名空间¶

PySparkScalaJava

spark = SparkSession.builder \
    .appName("lance-hive3-example") \
    .config("spark.sql.catalog.lance", "com.lancedb.lance.spark.LanceNamespaceSparkCatalog") \
    .config("spark.sql.catalog.lance.impl", "hive3") \
    .config("spark.sql.catalog.lance.parent", "hive") \
    .config("spark.sql.catalog.lance.parent_delimiter", ".") \
    .config("spark.sql.catalog.lance.hadoop.hive.metastore.uris", "thrift://metastore:9083") \
    .config("spark.sql.catalog.lance.client.pool-size", "5") \
    .config("spark.sql.catalog.lance.root", "hdfs://namenode:8020/lance") \
    .getOrCreate()

val spark = SparkSession.builder()
    .appName("lance-hive3-example")
    .config("spark.sql.catalog.lance", "com.lancedb.lance.spark.LanceNamespaceSparkCatalog")
    .config("spark.sql.catalog.lance.impl", "hive3")
    .config("spark.sql.catalog.lance.parent", "hive")
    .config("spark.sql.catalog.lance.parent_delimiter", ".")
    .config("spark.sql.catalog.lance.hadoop.hive.metastore.uris", "thrift://metastore:9083")
    .config("spark.sql.catalog.lance.client.pool-size", "5")
    .config("spark.sql.catalog.lance.root", "hdfs://namenode:8020/lance")
    .getOrCreate()

SparkSession spark = SparkSession.builder()
    .appName("lance-hive3-example")
    .config("spark.sql.catalog.lance", "com.lancedb.lance.spark.LanceNamespaceSparkCatalog")
    .config("spark.sql.catalog.lance.impl", "hive3")
    .config("spark.sql.catalog.lance.parent", "hive")
    .config("spark.sql.catalog.lance.parent_delimiter", ".")
    .config("spark.sql.catalog.lance.hadoop.hive.metastore.uris", "thrift://metastore:9083")
    .config("spark.sql.catalog.lance.client.pool-size", "5")
    .config("spark.sql.catalog.lance.root", "hdfs://namenode:8020/lance")
    .getOrCreate();

Hive 2.x 命名空间¶

PySparkScalaJava

spark = SparkSession.builder \
    .appName("lance-hive2-example") \
    .config("spark.sql.catalog.lance", "com.lancedb.lance.spark.LanceNamespaceSparkCatalog") \
    .config("spark.sql.catalog.lance.impl", "hive2") \
    .config("spark.sql.catalog.lance.hadoop.hive.metastore.uris", "thrift://metastore:9083") \
    .config("spark.sql.catalog.lance.client.pool-size", "3") \
    .config("spark.sql.catalog.lance.root", "hdfs://namenode:8020/lance") \
    .getOrCreate()

val spark = SparkSession.builder()
    .appName("lance-hive2-example")
    .config("spark.sql.catalog.lance", "com.lancedb.lance.spark.LanceNamespaceSparkCatalog")
    .config("spark.sql.catalog.lance.impl", "hive2")
    .config("spark.sql.catalog.lance.hadoop.hive.metastore.uris", "thrift://metastore:9083")
    .config("spark.sql.catalog.lance.client.pool-size", "3")
    .config("spark.sql.catalog.lance.root", "hdfs://namenode:8020/lance")
    .getOrCreate()

SparkSession spark = SparkSession.builder()
    .appName("lance-hive2-example")
    .config("spark.sql.catalog.lance", "com.lancedb.lance.spark.LanceNamespaceSparkCatalog")
    .config("spark.sql.catalog.lance.impl", "hive2")
    .config("spark.sql.catalog.lance.hadoop.hive.metastore.uris", "thrift://metastore:9083")
    .config("spark.sql.catalog.lance.client.pool-size", "3")
    .config("spark.sql.catalog.lance.root", "hdfs://namenode:8020/lance")
    .getOrCreate();

额外依赖¶

使用 Hive 命名空间需要主 Lance Spark 捆绑包之外的额外 JAR 包：- 对于 Hive 2.x：lance-namespace-hive2 - 对于 Hive 3.x：lance-namespace-hive3

Hive 3.x Spark Shell 示例

spark-shell \
  --packages com.lancedb:lance-spark-bundle-3.5_2.12:0.0.7,com.lancedb:lance-namespace-hive3:0.0.7 \
  --conf spark.sql.catalog.lance=com.lancedb.lance.spark.LanceNamespaceSparkCatalog \
  --conf spark.sql.catalog.lance.impl=hive3 \
  --conf spark.sql.catalog.lance.hadoop.hive.metastore.uris=thrift://metastore:9083 \
  --conf spark.sql.catalog.lance.root=hdfs://namenode:8020/lance

Hive 配置参数¶

参数	必需	描述
`spark.sql.catalog.{name}.hadoop.*`	✗	其他 Hadoop 配置选项，将覆盖默认的 Hadoop 配置
`spark.sql.catalog.{name}.client.pool-size`	✗	元数据存储客户端的连接池大小（默认：3）
`spark.sql.catalog.{name}.root`	✗	Lance 表的存储根位置（默认：当前目录）
`spark.sql.catalog.{name}.storage.*`	✗	其他存储配置选项
`spark.sql.catalog.{name}.parent`	✗	多级命名空间的父前缀（仅限 Hive 3.x，默认：`hive`）。有关详细信息，请参阅关于命名空间级别的说明。

关于命名空间级别的说明¶

Spark 提供至少 3 级层次结构：目录 → 多级命名空间 → 表。大多数用户将 Spark 视为具有 1 级命名空间的 3 级层次结构。

对于少于 3 级的命名空间¶

由于 Lance 允许像 DirectoryNamespace 这样的命名空间采用 2 级层次结构：根命名空间 → 表，因此 LanceNamespaceSparkCatalog 提供了一个配置 extra_level，它添加了一个额外的虚拟级别以匹配 Spark 层次结构，使其变为 根命名空间 → 虚拟额外级别 → 表。

目前，对于 DirectoryNamespace 和当 RestNamespace 无法响应 ListNamespaces 操作时，这会自动设置为 extra_level=default。如果您有相同行为的自定义命名空间实现，您也可以设置此配置以添加额外级别。

对于多于 3 级的命名空间¶

某些命名空间实现（如 Hive3）支持超过 3 级的层次结构。例如，Hive3 具有 4 级层次结构：根元数据存储 → 目录 → 数据库 → 表。

为了处理这种情况，LanceNamespaceSparkCatalog 提供 parent 和 parent_delimiter 配置，允许您指定一个父前缀，该前缀将添加到所有命名空间操作中。

例如，对于 Hive3：¶

设置 parent=hive 和 parent_delimiter=.
当 Spark 请求命名空间 ["database1"] 时，它会被转换为 ["hive", "database1"] 进行 API 调用
这使得 4 级 Hive 3 结构可以在 Spark 的 3 级模型中工作。

父配置有效地将您的 Spark 目录“锚定”在更深命名空间层次结构中的特定级别，使额外的级别对 Spark 用户透明，同时保持与底层命名空间实现的兼容性。