collections - Civium Wiki

Managing Collections

Most UUIDs are relatively long and arbitrary looking strings of characters, which do not in themselves tell us anything about the information held in their corresponding u-form. In order to find information in the commons, we don't try to remember individual UUIDs and type them in manually every time we want them. Instead, we gather UUIDs together in special collections and indexes.

A collection contains several UUIDs. For example, you may have a collection that contains pointers to the u-forms of all the countries in the world. That way, if you can find the UUID of the countries collection, you can find the UUID of any country by iterating through the collection.

Of course, this is only useful if you put your UUID into a collection and remember the UUID of the collection itself. Even if this collection is just called My Random UUIDs, it's better to remember one UUID for such a collection and let this collection contain links to all the u-forms you want to remember. If you want to keep notes telling you what each of these UUIDs refers to, there's a role called annotated collection which allows you to do this as well.

Collection Roles

At its simplest, a collection is a list of UUIDs that can be iterated through. There is a special role for collection which just has one special attribute, called members. This attribute contains a list of UUIDs that refer to the u-forms that are contained in the collection. The collection role also inherits from the entity role, so a collection may have a name, label and description.

A more detailed structure is the annotated collection, which contains extra metadata about the members in a parallel list called child_properties.

The roles for collection and annotated collection are here:

Collection	UUID: ~fd000a02510bfd17204424
Annotated Collection	UUID: ~fd000a02510bfdad92deec

To some extent, the use of both the 'members' and 'children' metaphors signifies some ovelap over whether collections are representing Boolean (set-theoretic) or Aristotelean (taxonomic) ideas of containment and inheritance. The answer for now is 'both'. Remember, roles are a guideline for interpretation of attribute names, not a strict ontology. However, there is some danger that calling too many attributes 'members' may enable a program to follow too many links in the Information Commons, which could reproduce many of the dangerous problems of a poorly-written web-spider.

Nested Collections

It's possible (and often desirable) for the members of a collection to be other collections. For example, the following UUID is the address of a version of the Bible in English.

http://uform.civium.net/construct/~018c63e2842c3011d9a00d59597e977efc

As well as a name and some bibliographic information, the main part of this u-form is a collection whose members points to a book of the Bible. Each of these book u-forms is mainly a collection, each of whose members points to a chapter, each of whose members points to an actual verse u-form. The verse u-forms do not have any members - instead they have an attribute text_content which contains the actual text of the Bible verse.

Scalable Collections

Simple collections are fine for many purposes, but suppose that you were dealing with a collection of UUIDs each of which referred to one person in the 2000 census of the population of the USA. Then you have a problem - in order to get the members of this collection, you would have to shepherd over a u-form whose members attribute contained many milliions of UUIDs.

An analogous problem is faced by large publications such as the Encyclopedia Brittanica. There is too much information in such an encyclopedia to fit into any one volume that you can physically take off a bookshelf and read, so the encyclopedia is segmented into a number of ordered volumes, each of which typically covers the entries from one part of the alphabet.

The scalable collection solves the engineering problem in the Information Commons in much the same way - by breaking the whole collection into segments, each of which is represented by a u-form of manageable size. This is implemented using the two roles below:

Scalable Collection Head Segment	UUID: ~01b8b8d720d01e11d8a50d487872f16706
Scalable Collection Segment	UUID: ~01d2021300d01d11d8932f026153455feb

The structure of the scalable collection as a whole is like a linked list - there is a head segment which is the first u-form in the chain, and then each subsequent member contains a pointer to the next segment in the list. This enables a program to start at the beginning of a scalable collection and eventually to collect all of its members, without ever having to shepherd across any u-form above a manageable size.

MAYA Design's Python API contains a module of functions which enable you to treat a scalable collection as if it is a simple Python list. This module is part of the utils library and can be imported using the command

from MAYA.utils import scalablecoll

Back to Civium Documentation