Repository Object Cache

The API efficiently loads, retains and releases content and objects from memory. When queries are performed or object fields are referenced in PHP, cScript and cTemplate, object field values are automatically loaded into the cache. As more memory is needed, the field values of objects that have not been accessed recently are released to free up more memory as needed. Modified field values will not be released to free up memory, to prevent updates from being lost before they are written back to the repository.

Populating the Object Cache

The repository object cache loads a "stub" for each object it encounters. The stub contains only basic information about the object, such as its Type, OID and some other metadata about the state of it's loaded and changed field values. Object stubs are currently retained and never released from memory for the duration of an opened repository connection. However, object field values are typically loaded in one of two ways:

Queries - When a SELECT clause is provided in a query, the corresponding fields are efficiently loaded in batch while loading the results. If no SELECT clause is provided, only the object stubs are loaded until a field value is referenced and loaded on demand (see next bullet).
On Demand - When a field value is referenced and it is not already loaded, the API will load and cache the field value the first time it is referenced. If the field is a non-blob data type value (numbers, dates and text, but not images and files), all other non-blob data type values will also be loaded and cached for the object. This is done because it is common to reference a number of object fields and it is more efficient to load them all together. Blob data type fields, such as images and files are loaded and cached individually. Content type fields referenced cause only their referenced object(s) stubs to be loaded and cached.

So, to improve performance, all fields that will be referenced in subsequent code should be added to the query's SELECT clause, to avoid unnecessary additional on demand loads.

Query SELECT Clauses

The SELECT clause of the query can affect loaded field values and impact performance, as explained above. Values can be selected (or not) in the different ways outlined below.

No SELECT - If no SELECT clause is specified, field values will be loaded on-demand when they are first accessed, which is less efficient than including the fields you will access in the SELECT clause to preload them.
SELECT dot-notation fields - In addition to the more obvious top-level fields, sub-field values for objects referenced or embedded within the selected object can also be preloaded to improve performance. Since the object structure is loaded, SELECT dot-notation fields will be preloaded into the object structure, and not flattened into field variables at the top-level of the object, like a traditional SQL query or SELECT alias (see next bullet) would.
SELECT aliases - When a SELECT clause includes an "AS" alias, the value selected will be available in a field/variable named after the specified alias. If the alias matches the name of a field, the alias value will override the field value and the field value will not be accessible. For more information, see cQL SELECT Aliases.

Releasing Cached Field Values

Once the allotted amount of memory available to the repository cache is reached and more memory is required to load new objects, the objects that have not been referenced in the longest amount of time will release their non-modified field values. By default, 80% of the memory available to PHP is allotted for the repository cache. This can be configured in config.php with the 'io_comand_memory' => [ 'tracker' => p ] config option where p is the percentage (80 by default).