Skip to content

README.md

Latest commit

 

History

History
148 lines (97 loc) · 5.87 KB

README.md

File metadata and controls

148 lines (97 loc) · 5.87 KB

lance-catalog-apache-client

Lance REST Catalog Specification

  • API version: 0.0.1

  • Generator version: 7.12.0

Lance Catalog is an open specification on top of the storage-based Lance open table and data format to standardize access to a collection of Lance tables. It describes how a catalog service like Apache Hive MetaStore (HMS), Apache Gravitino, Unity Catalog, etc. should store and use Lance tables, as well as how ML/AI tools and analytics compute engines (will together be called "tools" in this document) should integrate with Lance. A Lance catalog is a centralized repository for discovering, organizing, and managing Lance tables. It is a generalized concept that is also called namespace, metastore, database, schema in other similar systems. A Lance catalog can either contain a list of tables, or contain a list of Lance catalogs recursively. In an enterprise environment, typically there is a requirement to store tables in a catalog service such as Apache Hive MetaStore, Apache Gravitino, Unity Catalog, etc. for more advanced governance features around access control, auditing, lineage tracking, etc. Lance REST catalog is a standardized OpenAPI protocol to read, write and manage Lance tables.

Automatically generated by the OpenAPI Generator

Requirements

Building the API client library requires:

  1. Java 1.8+
  2. Maven/Gradle

Installation

To install the API client library to your local Maven repository, simply execute:

mvn clean install

To deploy it to a remote Maven repository instead, configure the settings of the repository and execute:

mvn clean deploy

Refer to the OSSRH Guide for more information.

Maven users

Add this dependency to your project's POM:

<dependency>
  <groupId>com.lancedb</groupId>
  <artifactId>lance-catalog-apache-client</artifactId>
  <version>0.0.1</version>
  <scope>compile</scope>
</dependency>

Gradle users

Add this dependency to your project's build file:

compile "com.lancedb:lance-catalog-apache-client:0.0.1"

Others

At first generate the JAR by executing:

mvn clean package

Then manually install the following JARs:

  • target/lance-catalog-apache-client-0.0.1.jar
  • target/lib/*.jar

Getting Started

Please follow the installation instruction and execute the following Java code:

import com.lancedb.lance.catalog.client.apache.*;
import com.lancedb.lance.catalog.client.apache.auth.*;
import com.lancedb.lance.catalog.client.apache.model.*;
import com.lancedb.lance.catalog.client.apache.api.CatalogApi;

public class CatalogApiExample {

    public static void main(String[] args) {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        defaultClient.setBasePath("http://localhost:2333");
        
        CatalogApi apiInstance = new CatalogApi(defaultClient);
        String catalog = "catalog_example"; // String | An identifier of the catalog.
        String catalogDelimiter = "."; // String | The delimiter used by the catalog identifier
        try {
            apiInstance.catalogExists(catalog, catalogDelimiter);
        } catch (ApiException e) {
            System.err.println("Exception when calling CatalogApi#catalogExists");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Reason: " + e.getResponseBody());
            System.err.println("Response headers: " + e.getResponseHeaders());
            e.printStackTrace();
        }
    }
}

Documentation for API Endpoints

All URIs are relative to http://localhost:2333

Class Method HTTP request Description
CatalogApi catalogExists HEAD /v1/catalogs/{catalog} Check if a catalog exists
CatalogApi createCatalog POST /v1/catalogs Create a new catalog. A catalog can manage either a collection of child catalogs, or a collection of tables. There are three modes when trying to create a catalog to differentiate the behavior when a catalog of the same name already exists: * CREATE: the operation fails with 400. * EXIST_OK: the operation succeeds and the existing catalog is kept. * OVERWRITE: the existing catalog is dropped and a new empty catalog with this name is created.
CatalogApi dropCatalog DELETE /v1/catalogs/{catalog} Drop a catalog. The catalog must be empty.
CatalogApi getCatalog GET /v1/catalogs/{catalog} Get information about a catalog
CatalogApi listCatalogs GET /v1/catalogs List all direct child catalogs of the root catalog.
TableApi getTable GET /v1/tables/{table} Get a table from the catalog
TableApi registerTable POST /v1/catalogs/{catalog}/register Register an existing table in the given catalog.
TableApi tableExists HEAD /v1/tables/{table} Check if a table exists

Documentation for Models

Documentation for Authorization

Endpoints do not require authorization.

Recommendation

It's recommended to create an instance of ApiClient per thread in a multithreaded environment to avoid any potential issues.

Author