Package com.apple.foundationdb.record.provider.foundationdb.keyspace

Class KeySpace

  • @API(MAINTAINED)
public class KeySpace
extends Object
    A KeySpace defines a logical directory structure for keys that comprise an FDB row key. Directories within a KeySpace are defined by the following attributes:
    • name - Defines a logical name for the directory. As with a directory in a filesystem, Within a given directory no two sub-directories may have the same name
    • type - Defines the datatype for the values stored at the directory's position within the FDB keyspace. No two directories may have the same type unless they are defined with different constant values. Note that NULL is considered a unique type, as such, all other types are implicitly non-null and any attempt to store a null value for those types will result in an error
    • constant - (optional) Defines a constant value for the directory within the FDB keyspace.

    Put visually, the following directory structure: 

      / (NULL)
     +- state (STRING)
        +- office_id (LONG)
           +- employees (STRING=E)
           |  +- employee_id (LONG)
           +- inventory (STRING=I)
           |  +- stock_id (LONG)
           +- sales (STRING=S)
              +- transaction_id (UUID)
              +- layaways (NULL)
                 +- transaction_id (UUID)
    defines a directory structure in which:
    • A state is represented by a string (presumably a value like * "CA", "NJ', "NY", etc.).
    • Within a state there are offices, each represented by a unique office_id.
    • Within a given office_id, there are three categories of information:
      • A set of employees (contained within a directory represented by the string "E"). Each employee is keyed by a LONG employee_id value.
      • The inventory of the office (contained within a directory represented by the string "I"). Each inventory item is keyed by a LONG stock_id value.
      • A list of sales transactions (contained within a directory represented by the string "S") Each transaction is represented by a UUID transaction_id value. There is a special location stored until the NULL key to indicate transactions that are layaways (haven't been fully paid for yet).

    Such a directory structure would be constructed as: 

      KeySpace keySpace = new KeySpace(
          new KeySpaceDirectory("state", KeyType.STRING)
              .addSubdirectory(new KeySpaceDirectory("office_id", KeyType.LONG)
                  .addSubdirectory(new KeySpaceDirectory("employees", KeyType.STRING, "E")
                      .addSubdirectory(new KeySpaceDirectory("employee_id", KeyType.LONG)))
                  .addSubdirectory(new KeySpaceDirectory("inventory", KeyType.STRING, "I")
                      .addSubdirectory(new KeySpaceDirectory("stock_id", KeyType.LONG)))
                  .addSubdirectory(new KeySpaceDirectory("sales", KeyType.STRING, "S")
                      .addSubdirectory(new KeySpaceDirectory("transaction_id", KeyType.UUID))
                      .addSubdirectory(new KeySpaceDirectory( "layaways", KeyType.NULL)))));

    Once defined, a KeySpace provides a convenient mechanism for constructing tuples that may then be used to form an FDB row key. For example: 

         Tuple transactionKey = keySpace.path("state", "CA")
         .add("office_id", 1234)
         .add("sales")
         .add("transaction_id", UUID.randomUUID())
         .toTuple(context);
    Creates a row key suitable to store a new sales transaction in California in office 1234.

    Similarly, a KeySpace can be used to take a given FDB row key and logically turn it back into the path from which it came: 

         KeySpacePath path = keySpace.pathFromKey(context, transactionKey);
     System.out.println(path.getDirectoryName());  //  Displays "transaction_id=XXXX-XXXX-XXXX-XXX""
     System.out.println(path.getParent().getDirectoryName());  //  Displays "sales"
     System.out.println(path.getParent().getParent().getDirectoryName());  //  Displays "office_id"