Relationship Query Support in Backend
How to use Search, BackendQuery, and Statement
Table of Contents
How to Call a Search of the Database ........................................................................................................... 1
BackendQuery: What It Is, and How to Build It ............................................................................................ 1
Statement ..................................................................................................................................................... 1
StatementMember ....................................................................................................................................... 2
IQueryValidator............................................................................................................................................. 2
ComparisonType ........................................................................................................................................... 2
How to Call a Search of the Database
The following Search method is supported through the IBackend interface:
IList<IBackendObject> Search(BackendQuery query)
All of the work is in crafting the BackendQuery, which is described below.
BackendQuery: What It Is, and How to Build It
A BackendQuery is essentially a list of relationship statements that contain variables. The Search
method above processes these statements in the order given, retrieving a list of all matching
relationships in the database, and intersecting the results from all statements together. BackendQuery
implements the IList interface, and may be thought of as an IList of Statements (which are described
below). It also implements the IQueryValidator interface, which is described below. BackendQuery also
contains additional properties, of which ResultName is the only one currently supported. This is the
name of the statement variable which should be used to create the IList returned by Search (in the
trivial case, for a BackendQuery with a single statement like “author1 authors ?content”, where ?
indicates a variable, and where “?content” is the ResultName, Search will return an IList of all Content
objects authored by “author1”).
Statement
The Statement class represents a single statement which describes a query of the relation datastore. It
contains four StatementMember fields, corresponding to the Subject, Predicate, Object, and Value of a
relation. It also contains a ComparisonType, which describes how the Value field should be used. Lastly,
Statement implements the IQueryValidator interface (described below).
StatementMember
A StatementMember is a struct with two fields: a string Value, and a boolean IsVariable. The Value field
is treated as a literal to be matched to this part of the statement in the relation datastore, when
IsVariable is false. If IsVariable is true, Value is treated as the name of a variable (thus not requiring any
special characters to indicate a variable). This variable name is not used for matching in the datastore,
but is used for matching with other statements to join results, and for matching with the BackendQuery
ResultName to determine which results should be returned to the caller of Search.
IQueryValidator
There are three methods in the IQueryValidator interface: IsValid and IsVariable which return a Boolean
value, and NumVariables, which returns an integer. In the case of Statement objects, IsValid returns
true if the Statement can be processed. This means that there are no null fields in the statement, and
especially that Predicate.Value and Value.Value both resolve into integers, unless Predicate.IsVariable
and Value.IsVariable are true, respectively. It also means that there are less than or equal to the
maximum allowed number of variables in that statement (the currently supported maximum number of
variables per statement is 1). Lastly, the Statement must contain a valid ComparisonType. In the case of
BackendQuery, IsValid returns true if IsValid returns true for all Statement objects in the BackendQuery.
IsVariable takes a string, and returns true if a variable in that statement has a name matching the passed
string. This is intended to allow determination of which Statement objects contain
BackendQuery.ResultName. For BackendQuery, IsVariable returns true if it returns true for any
Statement object within the BackendQuery.
NumVariables returns the number of StatementMembers within a Statement for which
StatementMember.IsVariable is true. For a BackendQuery, NumVariables returns the maximum number
of variables in any Statement in the BackendQuery.
ComparisonType
ComparisonType is an enum in the Common project which provides constant values which translate into
different comparison operations: ==, !=, <, <=, >, >=. It also contains a value for
ComparisonType.Unused. A ComparisonType is selected for each Statement, describing how the Value
field of the Statement is used. When the type is Unused, Value is ignored in the Statement and in the
datastore when searching for records matching the statement.
When one of the other comparisons is used, only results matching the Value plus comparison are
allowed. For example, if the statement is “Bob trusts ?person 5”, and the comparison is >, then the
results list will contain all users that Bob trusts with a trust strength greater than 5. If the comparison is
==, then the list contains users that Bob trusts with a strength of exactly 5, and so on.