This page describes an older version of the product. The latest stable version is 15.2.

Document API

Unlike POJOs, which force users to design a fixed data schema (in the form of a class definition) and adhere to it, a document is much more dynamic - users can add and remove properties at runtime as necessary. A Document always belongs to a certain type, represented by the class SpaceTypeDescriptor.

Before a certain Document instance is written to the space, its type should be introduced to it. The type has a name and controls metadata such as identifier property, routing property and which properties are initially indexed (naturally, you can also index new properties at runtime after adding them to your documents).

Tip

The Type controls metadata - so only the metadata is part of the type. A document can introduce new properties at will.

Note that the Document type does not describe the properties themselves (except for the names of the ID and Routing properties). These are completely dynamic and each instance can have a different set of properties (although in most cases Document instances of the same type are likely to have identical or similar set of properties).

Schema Evolution with Space Documents

Since a SpaceDocument is completely dynamic by nature, it is very easy to change or evolve your data model without ever taking down the Space. Simply change your application code to add additional properties or remove existing ones, and you’re good to go. Even better, old and new versions can co-exist since the space does not enforce any restriction with regards to the property set of documents that belong to a certain type. This is a much more lightweight model in comparison to the classic POJO model, where a recompilation and in many cases a full space restart is required to change the data schema.

If POJO model cannot be replaced with Document model, yet some level of schema evolution is desired within the POJO model, Dynamic Properties can be used.

Type Definition

Before we start writing and reading SpaceDocument from the space, we need an initial schema definition of the document type.

For example, suppose we’re implementing an electronic commerce system, and decided we need a type called Product with the following properties:

We also decide that CatalogNumber will be a primary key, partitioning will be done by the Category property, and the properties Name, Price should be indexed since they participate in most of the queries executed. Remember, the type definition is for metadata only, so we’re not concerned about Description and other such fields in the type definition, because Description isn’t used for indexing or any other metadata.

Note that this code does not reflect the complete model - most of the properties does not need to be introduced to the schema. Only properties with special roles (ID, Routing) are part of the schema definition. These meta model settings cannot be changed without restarting the space or dropping the type, clearing all its instances and reintroducing it again.

Creating and Writing Documents

To create a document create a Map<String,Object> with the requested properties, create a SpaceDocument object using the type name and properties, and write it to the space using the regular GigaSpace write method:

The GigaSpace.writeMultiple method can be used to write a batch of documents.

Update semantics are the same as POJO, except partial update that is not currently supported.

Use only alphanumeric characters (a-z, A-Z, 0-9) and the underscore (’_‘) to construct properties keys. Other characters might have a special behavior in GigaSpaces (for example: the dot (‘.’) is used to distinguish nested paths).

Reading and Removing Documents

There are three types of document queries:

Template Query

This type of query uses a SpaceDocument with type and any other set of properties values as a template for the query
For example: Read a document of type Product whose Name is Anvil:

All other Id based operations (readIfExists, takeById, takeIfExistsById, takeByIds) are supported for documents as well.

All overloads of those operations with timeout, transactions, modifiers etc. are supported for documents. The semantics is similar to POJOs.

Nested Properties

The Document properties values can be either scalars (integers, strings, enumerations, etc), collections (arrays, lists), or nested properties (Map or an extension of map, such as DocumentProperties). Values must adhere to the same restrictions as in the POJO model (e.g. be serializable). Nested properties can be queried by using the dot (‘.’) notation to describe paths, as shown above.

Note

It’s highly recommended to use DocumentProperties for nested documents since it contains performance and memory footprint optimizations which are tailored for GigaSpaces usage.

While it’s possible to use SpaceDocument as a property, it is probably a mistake, since it contains extra information which is not relevant for nested properties (type name, version, etc.).

Changing nested properties in an embedded space is not safe.

Document Hierarchy

SpaceDocument query supports hierarchical relationships so that entries of a child are visible in the context of the parent document, but not the other way around. For example, a document with name Employee can register its parent document Person in the following way:

Local Cache / Local View

Local View and Local Cache are supported for Documents. By default, the SpaceDocument instance is stored in the cache which speeds up query performance since the data does not need to be transformed from internal structure to SpaceDocument.