omnisci-rs

A Rust client for connecting to OmniSciDB via its RPC protocol of Thrift. This package takes care of creating a client with the Thrift binary protocol and buffered transport, and exposes all of the OmniSci Thrift types and methods for use with it.

Requirements

This client has been tested on these versions, and is expected to work with more recent versions unless otherwise noted:

• Rust 1.41+
• OmniSciDB 5.1+

It is also likely to work on earlier versions of OmniSciDB, but this is not officially supported.

How to use

Add omnisci to your Cargo.toml:

[dependencies]
omnisci = "0.1.0"

Then create a client and connect (to the 'Backend TCP' port on the OmniSciDB instance):

use omnisci;

let mut client = omnisci::client::create("127.0.0.1:6274")?;

let user = "admin".to_string();
let passwd = "HyperInteractive".to_string();
let database = "omnisci".to_string();

let session = client.connect(user, passwd, database)?;

let query = "SELECT * FROM flights_donotmodify LIMIT 5".to_string();
let columnar = false;
let nonce = "1".to_string();
let first_n = 10000;
let at_most_n = -1;

let results = client.sql_execute(session, query, columnar, nonce, first_n, at_most_n);

See the examples folder for a more complete example.

Contributing

Building

This project is built with Cargo, using cargo build. Each file in src/ except for lib.rs is automatically generated using Thrift, based on the the Thrift definitions stored at omniscidb (mapd.thrift, plus the .thrift files it references via include). To regenerate them, install Thrift 0.13.0 with your system's package manager, clone omniscidb locally, and then run:

./generate_thrift_bindings.sh ../omniscidb

All source is also formatted with rustfmt, via cargo fmt.

Testing

The integration tests expect a local running instance of OmniSciDB on the default Backend TCP port: http://localhost:6274

If running natively (such as with the ./startomnisci script), that port is accessible by default. If running with Docker, expose the Backend TCP port in addition to the default Frontend Web port using -p 6274:6274.

When ready, run cargo test.

License

This project is licensed under the MIT license.