substrait/
lib.rs

1// SPDX-License-Identifier: Apache-2.0
2
3//! [Substrait]: Cross-Language Serialization for Relational Algebra
4//!
5//! # Serialization and deserialization
6//!
7//! This crate provides generated types to serialize and deserialize Substrait
8//! data.
9//!
10//! ## Protobuf
11//!
12//! Protobuf serialization and deserialization are provided via [prost] in the
13//! [proto] module.
14//!
15//! ### Example
16//!
17//! #### Serialize and deserialize a plan
18//! ```rust
19//! # fn main() -> Result<(), prost::DecodeError> {
20//! use prost::Message;
21//! use substrait::proto::Plan;
22//!
23//! let plan = Plan::default();
24//!
25//! // Serialize the plan
26//! let encoded = plan.encode_to_vec();
27//!
28//! // Deserialize the buffer to a Plan
29//! let decoded = Plan::decode(encoded.as_slice())?;
30//!
31//! assert_eq!(plan, decoded);
32//! # Ok(()) }
33//! ```
34//!
35//! ### Serde support
36//!
37//! The `serde` feature generates serde implementations that match the [Protobuf JSON Mapping]
38//! via [pbjson].
39//!
40//! ##### Example
41//! ###### Deserialize a plan version using the `serde` feature
42//! ```rust
43//! # fn main() -> Result<(), serde_json::Error> {
44//! # #[cfg(feature="serde")] {
45//! use substrait::proto::Version;
46//!
47//! let version_json = r#"{
48//!   "minorNumber": 21
49//! }"#;
50//!
51//! let version = serde_json::from_str::<Version>(version_json)?;
52//! assert_eq!(
53//!   version,
54//!   Version {
55//!     minor_number: 21,
56//!     ..Default::default()
57//!   }
58//! );
59//! # } Ok(()) }
60//! ```
61//!
62//! ## Text
63//!
64//! Substrait defines a YAML schema for extensions. Types with serialization and
65//! deserialization support for these are provided via [typify] in the [text]
66//! module.
67//!
68//! ### Example
69//!
70//! #### Read a simple extension
71//! ```rust
72//! # #[cfg(feature="extensions")]
73//! # fn main() -> Result<(), serde_yaml::Error> {
74//! use substrait::text::simple_extensions::SimpleExtensions;
75//!
76//! let simple_extension_yaml = r#"
77//! %YAML 1.2
78//! ---
79//! scalar_functions:
80//!   -
81//!     name: "add"
82//!     description: "Add two values."
83//!     impls:
84//!       - args:
85//!          - name: x
86//!            value: i8
87//!          - name: y
88//!            value: i8
89//!         options:
90//!           overflow:
91//!             values: [ SILENT, SATURATE, ERROR ]
92//!         return: i8
93//! "#;
94//!
95//! let simple_extension = serde_yaml::from_str::<SimpleExtensions>(simple_extension_yaml)?;
96//!
97//! assert_eq!(simple_extension.scalar_functions.len(), 1);
98//! assert_eq!(simple_extension.scalar_functions[0].name, "add");
99//! # Ok(()) }
100//! # #[cfg(not(feature="extensions"))]
101//! # fn main() {}
102//! ```
103//!
104//! [pbjson]: https://docs.rs/pbjson
105//! [Protobuf JSON Mapping]:
106//!     https://developers.google.com/protocol-buffers/docs/proto3#json
107//! [Substrait]: https://substrait.io
108//! [typify]: https://docs.rs/typify
109
110#![doc(
111    html_logo_url = "https://raw.githubusercontent.com/substrait-io/substrait/main/site/docs/img/logo.svg",
112    html_favicon_url = "https://raw.githubusercontent.com/substrait-io/substrait/main/site/docs/img/logo.svg"
113)]
114#![cfg_attr(docsrs, feature(doc_auto_cfg))]
115#![deny(missing_docs)]
116
117#[cfg(feature = "extensions")]
118pub mod extensions;
119#[allow(missing_docs)]
120pub mod proto;
121#[allow(missing_docs)]
122pub mod text;
123pub mod version;
124
125#[cfg(feature = "parse")]
126pub mod parse;
substrait/lib.rs

substrait/
lib.rs
