Function cql_db::create_db

pub fn create_db<TStore: CqlType>(
    db_location: &str, 
    array_size: &[u64]
) -> Result<(), Error>

Creates an CQL database in the provided directory, if a database doesn't exist already.

There is an unchecked version of this function, allowing you to replace existing databases if needed.

Errors

Will return any I/O errors encountered during the execution of the function, including if a database already exists. Function may partially succeed resulting in changes to the file system if an I/O error has occured.

Additionally, the following Cql errors may be returned:

• A DimensionsOutOfRangeError will be returned if the provided array_size.len() is less than 1, or greater than u64::max_value() - 1.
• A DimensionTooSmallError will be returned if any of the provided capacities in array_size equal zero.

let result = match cql_db::create_db::<U64>(
    DATABASE_LOCATION,
    // not enough dimensions
    &[]
) {
    Err(error) => match error {
        error::Error::Cql(cql_error) => Some(cql_error),
        _ => None,
    }
    _ => None,
};

assert_eq!(
    result.unwrap(),
    Error::DimensionsOutOfRangeError {
        requested: 0,
        min: 1,
        max:u64::max_value() as usize - 1,
    }
);

let result2 = match cql_db::create_db::<U64>(
    DATABASE_LOCATION,
    // dimension is too small
    &[0]
) {
    Err(error) => match error {
        error::Error::Cql(cql_error) => Some(cql_error),
        _ => None,
    }
    _ => None,
};

assert_eq!(
    result2.unwrap(),
    Error::DimensionTooSmallError
);

Panics

Function should not panic. If you get it to panic, please raise an issue in github.

Examples

The below code creates a 2 dimensional array of [2, 3] storing unsigned 64bit integers:

use cql_u64::U64;

cql_db::create_db::<U64>(
    DATABASE_LOCATION,
    &[2, 3]
)?;

// created database will be matrix of zeros (default u64 value):
// [ 0, 0, 0, ]
// [ 0, 0, 0, ]

More complex databases can be created by increaing the length of the input array:

// 4 dimensional array:
cql_db::create_db::<U64>(
    DATABASE_LOCATION,
    &[2, 3, 4, 5]
)?;

// 10 dimensional array:
cql_db::create_db::<U64>(
    DATABASE_LOCATION,
    &[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
)?;

There are no restrictions on the shape of your databases, but it is usually better to have smaller dimensions at the start:

// This is valid:
cql_db::create_db::<U64>(
    DATABASE_LOCATION,
    &[20, 50, 3]
)?;

// However this will likely be both faster to read from, and save file space:
cql_db::create_db::<U64>(
    DATABASE_LOCATION,
    &[3, 20, 50]
)?;

But see the type(s) that you are interested in for performance benchmarks, and the index page to see how to calcuate file size requirements.