From 446e81a09cbbeecc1989a567a72f0f1dd4c62b11 Mon Sep 17 00:00:00 2001 From: Nikolay Ulmasov Date: Sat, 29 Jun 2024 22:32:57 +0100 Subject: [PATCH] Tidy up README.md Signed-off-by: Nikolay Ulmasov --- README.md | 68 ++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 57 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 006357d..4f5792b 100644 --- a/README.md +++ b/README.md @@ -2,11 +2,63 @@ [![CI](https://github.com/unitycatalog/unitycatalog-rs/workflows/CI/badge.svg)](https://github.com/unitycatalog/unitycatalog-rs/actions) ![crates.io](https://img.shields.io/crates/v/unitycatalog.svg?label=unitycatalog) ![crates.io](https://img.shields.io/crates/v/unitycatalog-client.svg?label=unitycatalog-client) ![crates.io](https://img.shields.io/crates/v/unitycatalog-sys.svg?label=unitycatalog-sys) -unitycatalog-rs serves an alternate implementation of the [Unity Catalog protocol](https://github.com/unitycatalog/unitycatalog/tree/main/api). The Unity Catalog protocol is a specification for a multi-modal catalog for data and AI assets. +**Unity Catalog Rust (UC-R)** + +A native Rust implementation of the [Unity Catalog](https://github.com/unitycatalog/unitycatalog): an Open and Multimodal Catalog for Data & AI. + +## Prerequisites + +- Install Rust, e.g. as described [here](https://doc.rust-lang.org/cargo/getting-started/installation.html) + +## [WIP] Quick Start + +Use two terminal windows: one to run the Unity Catalog Rust server (UC-R) another to explore the content of the UC-R server using varios client tools. + +### Run the server + +In the first terminal window, start the UC server (from the repository root directory) + +``` +cargo run +``` + +### [TBD] Query with DuckDB + +- [Install](https://duckdb.org/docs/installation/) DuckDB +- Start DuckDB (run `duckdb` in the terminal) +- Run the following commands in the DuckDB shell to install the required extensions +``` +install uc_catalog from core_nightly; +load uc_catalog; +install delta; +load delta; +``` + +- Attach the unity catalog to DuckDB +``` +ATTACH 'unity' AS unity (TYPE UC_CATALOG); +``` + +- Run the queries, for example +``` +SHOW ALL TABLES; +SELECT * from unity.default.numbers; +``` + +## APIs and Compatibility + +- Open API specification: The Unity Catalog Rest API is documented [here](https://github.com/unitycatalog/unitycatalog/tree/main/api). +- Compatibility and stability: The APIs are currently evolving and should not be assumed to be stable. + +## Compiling and Testing + +``` +cargo test +``` ## Why Rust? -Rust was chosen as a language for the second implementation for a few reasons: +Rust was chosen as a language for the alternative implementation for a few reasons: - **Performance**: Rust compiles to native bytecode, enabling it to be used in performance-critical and constrained environments. - **FFI**: As Rust uses the C ABI, bindings can be exposed to any language, like C, Go, etc. @@ -15,14 +67,8 @@ Rust was chosen as a language for the second implementation for a few reasons: - **Safety**: Rust's strong type system and ownership model make it difficult to write code that is unsafe or has undefined behavior. When dealing with data assets, especially when it comes to access control, this helps us ensure that we are not introducing security vulnerabilities. - **We want to write it!**: Most importantly, we like writing Rust! -## License - -Licensed under Apache License, Version 2.0 ([LICENSE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0) - -## Contribution +## Getting Involved -Unless you explicitly state otherwise, any contribution intentionally submitted -for inclusion in the work by you, as defined in the Apache-2.0 license, shall be -dual licensed as above, without any additional terms or conditions. +We encourage you to reach out and share your feedback or ideas by [raising an issue](issues/new). -See [CONTRIBUTING.md](CONTRIBUTING.md). +See [CONTRIBUTING.md](CONTRIBUTING.md) if you are looking to contribute. \ No newline at end of file