Most interesting functionality of Camlistore is implemented in terms of the search interface, which is provided by Camlistore’s indexer. It visits all of the stored blobs and discovers higher-level relationships between them based on its understanding of various schemas.
Search functionality is accessed via camlistore.Connection.searcher, which is a pre-configured instance of camlistore.searchclient.SearchClient.
Low-level interface to Camlistore indexer search operations.
The indexer component visits all blobs in the store and infers connections between them based on its knowledge of certain schema formats.
In particular, the indexer is responsible for tracking all of the modification claims for a permanode and providing its flattened attribute map for any given point in time.
However, the indexer also has special knowledge of the conventions around storage of filesystems and can thus be a more convenient interface for filesystem traversal than the raw blob interface.
Callers should not instantiate this class directly. Instead, call camlistore.connect() to obtain a camlistore.Connection object and access camlistore.Connection.searcher.
Request a description of a particular blob, returning a BlobDescription object.
The “description” of a blob is the indexer’s record of the blob, so it contains only the subset of information retained by the indexer. The level of detail in the returned object will thus depend on what the indexer knows about the given object.
Get the claims for a particular permanode, as an iterable of ClaimMeta.
The concept of “claims” is what allows a permanode to appear mutable even though the underlying storage is immutable. The indexer processes each of the valid claims on a given permanode to produce an aggregated set of its attributes for a given point in time.
Most callers should prefer to use describe_blob() instead, since that returns the flattened result of processing all attributes, rather than requiring the client to process the claims itself.
One important feature of search interface is its ability to obtain the current state of a mutable object, or even its state at a particular point in time.
camlistore.searchclient.SearchClient.describe_blob() takes a blobref and returns a camlistore.searchclient.BlobDescription object that provides access to the index metadata for the given blob, as well as efficient access to descriptions of related objects.
Represents the indexer’s description of a blob, from SearchClient.describe_blob().
Obtain a description of another related blob.
When asked for a description, the indexer also returns descriptions of some of the objects related to the requested object, such as the files in a directory.
This interface allows callers to retrieve related objects while possibly making use of that already-retrieved data, falling back on a new call to the indexer if the requested blob was not already described.
Since this method sometimes uses data retrieved earlier, it may return stale data. If the latest data is absolutely required, prefer to call directly SearchClient.describe_blob().
The other main capability of the search interface is querying the store to find objects fitting certain criteria.
camlistore.searchclient.SearchClient.query is the interface to this functionality, returning an iterable of camlistore.searchclient.SearchResult objects.
The mechanism by which Camlistore implements mutable objects is via permanodes which act as an immitable persistent “name” for a mutable object, and claims which describe mutations of permanodes.
Most callers will use the flattened list of permanode attributes provided by camlistore.searchclient.SearchClient.describe_blob(), but it is also possible to access the raw claim list for a permanode via camlistore.searchclient.SearchClient.get_claims_for_permanode(), which returns an iterable of camlistore.searchclient.ClaimMeta objects.
Description of a claim.
A claim is a description of a mutation against a permanode. The indexer aggregates claims to decide the state of a permanode for a given point in time.
The type attribute represents the kind of mutation, and a different subset of the other attributes will be populated depending on that type.
For claims that mutate attributes, the name of the attribute that this claim mutates, as a string.
The blobref of the public key of the party that made this claim, against which the claim’s signature was verified.