Documentation for Chandler Query (Find, Search) System

Query String Syntax:

There are several kinds of queries. Simple queries are queries over sets of items. You can write a simple query using the for statement. Compound queries are queries composed from other queries.

Keywords and required tokens in a query are shown in bold. The portions of the query that you supply are written in italics

for queries

for var (in | inevery) set where boolean-condition

Here's what you need to supply for the various portions of a for query:

var - For now, you should use 'i'. This constraint will be removed in the future.

set - At the moment you can supply one of three possibilities for set:

1. repository paths for Kind names, enclosed in "" or ''
2. parameters. A parameter is a $ followed by at least one digit. You can pass a ref-collection as a parameter to do a query over a ref-collection.
3. ftcontains( lucene-query , attr-name1 , ... , attr-namen ) - The source is the result of a full text query using the lucene-query, and returns items where the search text appears in any attribute whose name is listed in attr-name1 ... attr-namen. The list of attributes names is optional (all attributes will be searched in this case).

boolean condition

The result of the query is those items from the set which satisfy the boolean condition. The condition is a boolean expression composed in the usual infix style. Here are the elements that you can use in the boolean condition.

• the names of Chandler item attributes

• unary (prefix) operators
  • +
  • -
  • not

• boolean operators:
  • and
  • or
  • not

• relational operators:
  • >=
  • <=
  • >
  • <
  • ==
  • !=

• arithmetic operators:
  • +
  • -
  • *
  • /
  • div
  • mod

• dates: you can supply dates and times in eGenix mxDateTime ISO format like this: date( ISO-date-string )

• functions: the set of functions is restricted but easily extended
  • len( expr ) - returns the length of the expression
  • contains( string, substring ) - returns true if string contains substring

• methods on items:
  • hasAttribute( string ) - a method on Chandler Items that returns True if the Item has an attribute named string. Invoke via i.hasAttribute( string ), where i is the query iteration variable

If your for query is iterating over Kinds, and you want to include items of a Kind's subkind, you should use the keyword inevery instead of in

union queries:

union(*_query1_, query2, ... , _queryn_)*

Compute the union of queries 1..n and return that as the result.

intersection queries

intersect(*_query1_, _query2_)*

Compute the intersection of query1 and query2 and return that as the result.

difference queries

difference(*_query1_, _query2_)*

Compute the difference of query1 and query2 and return that as the result.

repository.query.Query API

Creation

To use a query, your code will look something like this

import repository.query.Query as Query

p = rep.findPath('//Queries')
k = rep.findPath('//Schema/Core/Query')
q = Query.Query("for i in '//Schema/Core/Kind' where True", p, k)

for i in q:
    print i

A Query is a Chandler Item, so you must supply the repository parent and kind of the item being created. In the Chandler application, the parent should be '//Queries'.

Parameters

If your query uses parameters, you should set the args attribute to a dict keyed by the parameter name, including the "$". The value of an entry in the dict depends on how you used the parameter in the query. If you used the parameter to indicate a ref-collection between the in and where keywords, then the value of the entry should be a tuple of the UUID of the item containing the reference collection, and a string which is the name of the reference collection attribute. If you used the parameter in the boolean condition, then the value is a single valued tuple containing the value you wish to pass as an argument.

So for example,

An argument used in the boolean condition

q.args["$0"] = ( data, )

An argument used to specify a reference collection as the source of a query

q.args["$0"] = ( item.itsUUID, "attributeName" )

Notification

A key feature of Chandler queries is change notification. A Chandler query defines a set of items. The notification mechanism makes sure that the result set of the query always contains the correct Items. If you change an item so that it satisfies the conditions of some query, the notification mechanism will add that item to the result set of the query. If you change an item so that it no longer satisifies the conditions of a query then the notification mechanism will remove that item from the result set of that query. The query notification mechanism does not indicate that any attribute of any item in a query's result set has changed. It just keeps the right items in the result set.

Clients of a query can request that they be notified when the query notification mechanism notices items that enter or exit the query result set. Your client code supplies a Chandler item which has a callback method. In the Chandler application, this item will usually be an ItemCollection. The callback method will be passed a tuple containing two lists: a list of the UUID's of any items added to the query result and a list of the UUID's of any items removed from the query result.

You supply a callback item with the subscribe method on Query. This method has two mandatory parameters and two optional parameters. The first parameter is an Item that has the required callback item, and the second parameter is that name of that callback method.

The two optional parameters are a little more difficult to explain. The repository's concurrency model gives each thread a separate view of the items in the repository. You can select when you would like to be notified of changes. The options are:

1. be notified of changes that happen in your view (the same view that the query is being run in) - instantaneously
2. be notified of changes that happen on views outside your own - when your view commits
3. be notified of both kinds of changes

The default is to be notified of both kinds of changes. The optional parameters are Booleans that you can set to False if you don't want to be notified if changes in your view (the first optional parameter) or of changes in other view (the second optional parameter)

No matter how you set the view notification parameters, you will only be notified of changes that would add or remove items from the query result set.

-- TedLeung - 09 Mar 2005