Basic InfinityDB Operations

1. Introduction
2. Creating and opening a database
3. Allocating and disposing a Cu cursor
4. Updates: insert() and delete()
5. The ItemSpace data model
6. The contents of an Item: components
7. The retrieval operations

Introduction

Example code launch scripts are in installation-root/examples and source is in installation-root/src/com/infinitydb/examples. Start with HelloWorld.java, then see DemoSnippets.java or PatientExample.java. This document is independent of the examples. Also, "ItemSpace Data Structures.pdf" will be interesting as it explains some possible mappings between the base API and upper layers.  

Creating and opening a database

import com.infinitydb.InfinityDB;
	..
	// create a db
    String fileName = "c:/temp/testdb.idb";
    InfinityDB db = InfinityDB.create(fileName, true/*overwrite if exists*/);
    ...    
    // or, if a db file already exists:
    ...
    InfinityDB db = InfinityDB.open(fileName, true/*allow updates*/);

Later, the code will just refer to db, meaning a database opened or created this way.  

Allocating and disposing of a Cu cursor

    Cu cu = Cu.alloc();
    try {
        // use cu in various ways to do database updates and retrievals
    } finally {
        cu.dispose(); // this is optional, for speed
    }

A Cu can only be used by one Thread at a time, although any number of Threads can be using the database with different Cu's at a time. (To detect whether an application is accidentally sharing Cu's, use InfinityDB.setCheckForConcurrentCuModification(true).) A single Thread will often allocate multiple Cu's at a time, but they are almost always only used for a short time before being disposed.  

Updates: insert() and delete()

    cu.clear().append("hello world"); // Temporarily use Cu.
    db.insert(cu); // Now db contains one more 'Item'

The ItemSpace data model

The Items in an ItemSpace are kept in ascending order; for comparison purposes, the initial chars of an Item are most significant, and an Item that is a prefix of another is smallest. There is no inherent limit to the number of Items in an ItemSpace. There is no other information in an ItemSpace beyond the Items themselves: there is no separate 'data' or 'record' attached to an Item. There is no flat file or other separate data store. Only the Items in the ItemSpace, which is in one InfinityDB file, contain all of the information. An ItemSpace can also be empty.

A Cu cursor contains no information other than a single Item and is not connected to a particular ItemSpace in any way. Since an Item is not an Object, but just a conceptual sequence of chars, it can live equally well either in an ItemSpace or in a Cu or anywhere else, such as in a char[] or, less often, a byte[]. The Item in a Cu does not need to be in the ItemSpace.

The Items in an ItemSpace can be inserted and deleted randomly and can be retrieved randomly or sequentially in both directions by using a Cu. At the ItemSpace level, there are no semantics attached to the Items, and the fundamental operations are very simple. The simplicity of this lowest-level data view allows the InfinityDB engine to concentrate on performance, while semantics are applied by upper layers.

In order for this basic data model to be useful, the sorted sequence of Items in the ItemSpace needs to be organized. This is partially accomplished by keeping related Items together by sharing a prefix of some kind: this is a very general concept and it shows up in many higher-level structures. Another organizational idea is the component which is described next.  

The contents of an Item: Components

    cu.clear().append("a string").append(5).append(2.6).append(true);
    System.out.println(cu);
    // prints:
    // "a string" 5 2.6 true
    // This is not what StringBuffer would print!

Now we can parse back these primitives:

    int offset = 0;
    String s = cu.stringAt(offset); // get the initial string component
    offset = cu.skipComponent(offset); // parse over the string
    long n = cu.longAt(offset); // get back the long
    offset = cu.skipComponent(offset); // skip the long
    double d = cu.doubleAt(offset);
    offset = cu.skipComponent(offset);
    boolean b = cu.booleanAt(offset);

Given the Java primitives, a wide range of applications of the ItemSpace model is possible, but there are other component types that help in creating further semantic levels, which will be described in further sections. For a complete description of each component type, see the javadoc for Cu. Also note the Component Type Printable Representations section. For now, lets investigate getting back information from a set of component-structured Items in the ItemSpace db.  

The simple retrieval operations

    cu.clear().append("customers").append("mary");
    db.insert(cu);
    cu.clear().append("customers").append("john");
    db.insert(cu);
    
    // and so on. Now retrieve the set of customer names
    
    cu.clear().append("customers"); // the prefix for all customers
    int prefixLength = cu.length(); // the size of the Item in cu
    while (db.next(cu, prefixLength)) {
        System.out.println(cu.stringAt(prefixLength));
    }

It is important to note here that it is very efficient in any normal ItemSpace to store Items with shared prefixes: the shared prefixes are compressed out (with character granularity). This is only an implementation detail, but it nevertheless affects how we think about organizing the entire database. We often store huge numbers of Items with sometimes long common prefixes.

There are also operations for scanning backwards, and for scanning without skipping the given Item if present in the db. All of these operations interpret the two parameters the same way, as described above. The operations are:

method	direction	skip
boolean next(Cu cu, int protectedPrefixLength) throws IOException	forwards	given Item skipped if present
boolean first(Cu cu, int protectedPrefixLength) throws IOException	forwards	given Item not skipped if present
boolean previous(Cu cu, int protectedPrefixLength) throws IOException	backwards	given Item skipped if present
boolean last(Cu cu, int protectedPrefixLength) throws IOException	backwards	given Item not skipped if present

 

Getting back a Record

	// We have a customerId of any primitive type. Create and save a record for it.
	long customerId = 1000;
	long zipCode = 91633;
	String spouseName = "Cynthia";
	double balance = 918.31;
	..
	cu.append("customer table").append(customerId).append(zipCode).append(spouseName).append(balance);
	db.insert(cu); // create a single 'record' in the "customer table"
	// we have ignored deleting a previous customer record if necessary

	printCustomer(long customerId) {
		Cu cu = cu.alloc().append("customer table").append(customerId); // the prefix
		int protectedPrefixLength = cu.length(); // how many chars to preserve at start of cu
		if (db.next(cu, protectedPrefixLength)) {
			int offset = protectedPrefixLength; // offset moves rightwards through the record
			long zipCode = cu.longAt(offset); // get long component's value at offset in the record
			int offset = cu.skipLong(offset); // move over zipCode to spouseName
			String spouseName = cu.stringAt(offset); // get string component's value at offset in the record
			offset = cu.skipString();
			double balance = cu.doubleAt(offset);
			// do something with zipCode, spouseName, balance, etc. 
		} else .. // record not present. Cu not modified
	}

Now suppose we want to access by zipCode. We need to insert Items with a different sequence of components that will sort by zipCode. Here is how to insert them:

	// Create and save a zipCode index entry on customers.
	// Do this when the customer row is inserted.
	cu.append("customers by zipcode index").append(zipCode).append(customerId);
	db.insert(cu);

	// loop over customers in the index given zipCode
    cu.clear().append("customers by zipcode index").append(zipCode);
    int prefixLength = cu.length(); // the size of the Item in cu
    while (db.next(cu, prefixLength)) {
    	long customerId = cu.longAt(prefixLength);
    	printCustomer(customerId); // method defined above
    }

Previous Next