Namespaces and tables

Like a relational database, Hypertable represents data as tables of information. Namespaces provide a way to logically group tables together and are analogous to the directory hierarchy in a modern filesystem. Namespaces allow you to organize your tables into related groups, keeping table names simple, as table names need only be unique within the namespace in which they are created. All Hypertable instances have a built-in default root namespace "/".

 

The IClient interface provides methods for creating, opening and dropping namespaces. The INamepace interface also provides methods for executing HQL commands or HQL queries. For example, open an existing namespace or create it if not exist:

var connectionString = "Provider=Hyper;Uri=net.tcp://localhost";
using (var context = Context.Create(connectionString))
using (var client = context.CreateClient())
using (var ns = client.OpenNamepace("example", OpenDispositions.OpenAlways)) {
   // use the namespace
}

 

A table consists of a set of column family and access group specifications defined by a table schema. Column families are somewhat analogous to a traditional database column. The main difference is that a theoretically infinite number of qualified columns can be created within a column family. The qualifier is an optional NUL- terminated string that can be supplied, along with the data, in the insert statement. This is what gives tables in Hypertable their sparse nature; see also the HQL CREATE TABLE reference. Access Groups provide a way to control the physical storage of column data to optimize disk I/O. Access Groups are defined in the table schema and instruct Hypertable to physically store all data for columns within the same access group together on disk. This feature allows you optimize queries for columns that are accessed with high frequency by reducing the amount of data transferred from disk during query execution. Disk I/O is limited to just the data from the access groups of the columns specified in the query. For example, creating a table using HQL:

string hql = 
   "CREATE TABLE user ("
+  "name,"
+  "address,"
+  "photo MAX_VERSIONS=5,"
+  "profile,"
+  "ACCESS GROUP default (name, address, photo),"
+  "ACCESS GROUP profile (profile)"
+  ");";

var connectionString = "Provider=Hyper;Uri=net.tcp://localhost";
using (var context = Context.Create(connectionString))
using (var client = context.CreateClient())
using (var ns = client.OpenNamepace("example", OpenDispositions.OpenAlways)) {
  ns.Exec(hql);
  using (var table = ns.OpenTable("user")) {
    // use the table
  }
}

 

Alternativ to the HQL CREATE TABLE command, the xml table schema representation can be used to create or alter tables. For example, open an existing table or create it if not exist:

string schema = 
   "<Schema>"
+     "<AccessGroup>"
+       "<ColumnFamily>"
+           "<Name>name</Name>"
+       "</ColumnFamily>"
+       "<ColumnFamily>"
+           "<Name>address</Name>"
+       "</ColumnFamily>"
+       "<ColumnFamily>"
+           "<Name>Photo</Name>"
+           "<Options>"
+              "<MaxVersions>5</MaxVersions>"
+           "</Options>"
+       "</ColumnFamily>"
+     "</AccessGroup>"
+     "<AccessGroup name=\"profile\">"
+       "<ColumnFamily>"
+           "<Name>profile</Name>"
+       "</ColumnFamily>"
+     "</AccessGroup>"
+ "</Schema>";

var connectionString = "Provider=Hyper;Uri=net.tcp://localhost";
using (var context = Context.Create(connectionString))
using (var client = context.CreateClient())
using (var ns = client.OpenNamepace("example", OpenDispositions.OpenAlways))
using (var table = ns.OpenTable("user", schema, OpenDispositions.OpenAlways)) {
   // use the table
}

 

The TableSchema class provides methods for parsing and rendering the xml table schema. For example, create a xml table schema:

var schema = new TableSchema { AccessGroups = new List<AccessGroup>() };

var accessGroup = new AccessGroup { ColumnFamilies = new List<ColumnFamily>() };
accessGroup.ColumnFamilies.Add(new ColumnFamily { Name = "name" });
accessGroup.ColumnFamilies.Add(new ColumnFamily { Name = "address" });
accessGroup.ColumnFamilies.Add(new ColumnFamily { Name = "photo", Options = new ColumnFamilyOptions { MaxVersions = 5, MaxVersionsSpecified = true } });

schema.AccessGroups.Add(accessGroup);

accessGroup = new AccessGroup { Name = "profile", ColumnFamilies = new List<ColumnFamily>() };
accessGroup.ColumnFamilies.Add(new ColumnFamily { Name = "profile" });

schema.AccessGroups.Add(accessGroup);

var xml = schema.ToString();

 

Regarding the different table, access group and colunm family options please refer to the HQL CREATE TABLE command.