Documentation

Get started within minutes.

Prerequisites

Assumptions

All of RogueDB's Proto files and Root CA Certificate are located in a folder called: roguedb. All of your Protocol Buffer files are located in a folder called: data_schemas.

This is not required. The examples will need to be altered in accordance to your directory structure and placement of files.

Supporting functions implementation denoted by a comment of "See Reference Functions..." are excluded for clarity and not required to use RogueDB, but the implementations are included at the bottom for your convenience.

Initial Connection

The following code establishes a connection to the configuration and interface services. We suggest either using our public libraries to reduce the few lines of boilerplate code or creating your own internal library.

  • ConfigurationStub provides access to manage schemas and state of a RogueDB instance.
  • InterfaceStub provides access to create, read, update, and delete operations (eg. CRUD operations) with a RogueDB instance.

Schema Registration

There are two primary steps for registering schema with a RogueDB database:

  • Identify the indices in the Protocol Buffer definition.
  • Provide the schemas to RogueDB.
Marking Indices

The first step of registering a Protocol Buffer is to mark the fields to be used for indexing with the pattern: // index-# (ex. // index-1). All schemas must have indices for use with RogueDB.

Guidelines for these fields are the following:

  • Fields selected for an index should form a unique key (aka identifier)
  • Indices should be ordered in the way you think about data for most efficient look-up.

An example inspired by financial market data:

Observe that symbol, timestamp, and aggregate_period are selected for the indices. When thinking about market data, the symbol is often the first field to come to mind followed by the aggregate period (1 min., 5 min., etc.) and finally the time of recording (aka timestamp). These three fields prevent collision and form a unique idea for any instance of an Aggregate.

Registering Schemas

The requirements to register your schema are the following:

  • Filename of the schema consisting only of alphanumerical and underscore ("_") characters.
  • Contents of the schema as a string.
  • Source type (ex. Protocol Buffers).
  • One message per file. Multiple messages supported in an upcoming release.

CRUD Operations

All operations do not require a special structured querying language (eg. SQL) to execute. The API has been defined to mimic common standard data structures such as dictionaries, set, vectors, lists, and other data structures. A Payload must consist of only one schema, but all Payloads do not have to have the same schema. Failure to adhere to this requirement will result in the query not executing.

Below is the Test schema used in the examples below:

Create

There are no differences in single versus batch create operations in terms of API.

Update

There are no differences in single versus batch update operations in terms of API.

Delete

There are no differences in single versus batch delete operations in terms of API.

Read

RogueDB's querying API allows programmatic composition by using logical operators (&&, ||) and comparison operators (==, !=, <, <=, >, >=) to replicate conditionals in your native progamming language. There are no joins, inner joins, outer joins, wheres, on, as, or any other special keywords required to be learned as a result.

A query can use an entire message with its indices or specifying individual fields as the operands in a query. RogueDB supports basic queries that involve the same logical operator (eg. homogenous application) and a single schema. There must be a 1:1 or 1:1:1 of operand and conditional or operand, conditional, and operand field for the query to be valid.

Future support is coming for complex queries that involve combining different logical operators for a single schema and support for  multiple schemas in a single query.

The following example demonstrates using a schema's indices as the operand:

The following example demonstrates using a schema's fields as the operand:

User Roles and Permissions

RogueDB supports the creation of users and assigning of permissions on a schema level basis. Your API access key associated with your subscription has all permissions by default and cannot be revoked. Users have no permissions by default. The following permissions can be assigned:

  • Read: The ability to perform the Read operation (aka search) for a schema.
  • Write: The ability to perform the Create, Update, and Delete operations (aka insert, update, and remove) for a schema.
  • Execute: The ability to modify a schema's definition through the Configuration service.
  • Admin: Grants all permissions and overrides any existing permission.

Permissions flow downwards from the parent schema. For instance, consider the following example:

Now presume we have a user, Foo, with the following permissions:

  • MedicalRecords: No permissions by default.
  • FinancialRecords: Read permissions.
  • Customer: Write and Read permissions.

Due to the composition of Customer including MedicalRecords and FinancialRecords, Foo can do the following when using Customer as the record:

  • MedicalRecords: No permissions by default => Write and Read permissions.
  • FinancialRecords: Read permissions => Write and Read permissions.

Careful consideration needs to be made when designing schemas to ensure permissions do not propagate in unexpected ways. As such, the Execute permission and Admin role should be given sparingly, if at all, and under additional security mechanisms.

Design Suggestion

Creation of a unique ID per customer with storage of MedicalRecords, FinancialRecords, and PII as separate schemas in the database prevents propagation of permissions. This further streamlines efficient storage and retrieval of data to only the required components versus the entirety of a record. UUIDs are an excellent mechanism for unique identifiers.

Consider the following as a more secure alternative:

Usage

RogueDB uses a case insensitive mapping of schema to permissions. The following is an example of User creation:

Error Handling

RogueDB reports all error details in the Response message returned. The following example demonstrates parsing the errors returned:

Reference Functions

Functions used in the examples that are not required. Below are the implementation details for your convenience to get an even quicker start to using RogueDB.

Still have questions?

Please reach out for additional clarification.

First Mover Advantage
Limited Availability Discounts

0-1,000 Users: 50% Discount. Promo: FIRST1K
1,001-5,000 Users: 25% Discount. Promo: FIRST5K
5,001-10,000 Users: 10% Discount. Promo: FIRST10K