Development Team/Low-level Activity API: Difference between revisions

Line 185:

Activities may query the datastore:

(results,count) = datastore.find(query)

(results,count) = datastore.find(query, properties)

It returns the ~~results~~ as array of ~~properties~~ and a count of matching items (the array may have fewer items if the query was limited). In addition to the usual metadata items, ~~the properties~~ will include the object id at key 'uid', the mountpoint of the item at key 'mountpoint', and possibly a 'filename' if requested.

It returns the matching object's metadata as array of dictionaries, and a count of matching items (the array may have fewer items if the query was limited). In addition to the usual metadata items, each dictionary will include the object id at key 'uid', the mountpoint of the item at key 'mountpoint', and possibly a 'filename' if requested.

The ~~query can~~ be a:

The '''properties''' argument is an array of strings. It defines which keys to include in the result. You should only specify the keys you actually need. If you pass an empty array here, all the metadata would be returned, which for a Journal with hundreds of entries and previews could amount to multiple megabytes of data.

~~: string: fulltext search~~

The '''query''' argument is a dictionary. If empty, all the datastore's entries will be returned, but again, you should avoid that. The key-value pairs specify the value (or array of values, or dictionary specifying range) for a specific property, e.g.:

~~:: the given string~~ is ~~searched in~~ all ~~text properties~~

: 'title' = 'First Project' (but see note below)

~~: dictionary: structured query~~

: 'mime_type' = ['image/png', 'image/jpeg']

:: the key-value pairs ~~in the dictionary~~ specify the value (or array of values, or dictionary specifying range) for a specific property, e.g.:

: 'mtime' = {'start' = '2007-07-01T00:00:00', 'end' = '2007-08-01T00:00:00'}

::: 'title' = 'First Project' (but see note below)

A few specific keys adjust the query:

::: 'mime_type' = ['image/png', 'image/jpeg']

: 'query': fulltext search term

::: 'mtime' = {'start' = '2007-07-01T00:00:00', 'end' = '2007-08-01T00:00:00'}

: 'order_by': key (or array of keys) to order results by, to reverse order use '-key' (but see note below)

~~:: also, there are a~~ few specific keys to adjust the query:

: 'limit', 'offset': return only limit results starting at offset

::: 'query': fulltext search term

: 'mountpoints': array of [[#Mount Points|mountpoint ids]] to search (or all if not specified)

::: 'order_by': key (or array of keys) to order results by, to reverse order use '-key' (but see note below)

: 'include_files': if true, generate files as if get_filename() had been called for each item. In results, a property 'filename' will be added.

::: 'limit', 'offset': return only limit results starting at offset

::: 'mountpoints': array of [[#Mount Points|mountpoint ids]] to search (or all if not specified)

::: 'include_files': if true, generate files as if get_filename() had been called for each item. In results, a property 'filename' will be added.

NOTE: Since Sugar 0.84 only very few keys are supported ('uid', 'activity', 'activity_id', 'mime_type', and 'keep', see [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/master/src/carquinyol/indexstore.py#line32 here]). Other keys are ignored so you may get back more results than expected. Results are ordered by timestamp by default. Sort keys are limited, too (none in 0.84, in 0.86 'timestamp' and 'title', see [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/master/src/carquinyol/indexstore.py#line266 here]).

@@ Line 185: / Line 185: @@
 Activities may query the datastore:
-  (results,count) = datastore.find(query)
+  (results,count) = datastore.find(query, properties)
-It returns the results as array of properties and a count of matching items (the array may have fewer items if the query was limited). In addition to the usual metadata items, the properties will include the object id at key 'uid', the mountpoint of the item at key 'mountpoint', and possibly a 'filename' if requested.
+It returns the matching object's metadata as array of dictionaries, and a count of matching items (the array may have fewer items if the query was limited). In addition to the usual metadata items, each dictionary will include the object id at key 'uid', the mountpoint of the item at key 'mountpoint', and possibly a 'filename' if requested.
-The query can be a:
+The '''properties''' argument is an array of strings. It defines which keys to include in the result. You should only specify the keys you actually need. If you pass an empty array here, all the metadata would be returned, which for a Journal with hundreds of entries and previews could amount to multiple megabytes of data.
-: <b>string</b>: fulltext search
+The '''query''' argument is a dictionary. If empty, all the datastore's entries will be returned, but again, you should avoid that. The key-value pairs specify the value (or array of values, or dictionary specifying range) for a specific property, e.g.:
-:: the given string is searched in all text properties
+: 'title' = 'First Project' <i>(but see note below)</i>
-: <b>dictionary</b>: structured query
+: 'mime_type' = ['image/png', 'image/jpeg']
-:: the key-value pairs in the dictionary specify the value (or array of values, or dictionary specifying range) for a specific property, e.g.:
+: 'mtime' = {'start' = '2007-07-01T00:00:00', 'end' = '2007-08-01T00:00:00'}
-::: 'title' = 'First Project' <i>(but see note below)</i>
+A few specific keys adjust the query:
-::: 'mime_type' = ['image/png', 'image/jpeg']
+: 'query': fulltext search term
-::: 'mtime' = {'start' = '2007-07-01T00:00:00', 'end' = '2007-08-01T00:00:00'}
+: 'order_by': key (or array of keys) to order results by, to reverse order use '-key' <i>(but see note below)</i>
-:: also, there are a few specific keys to adjust the query:
+: 'limit', 'offset': return only limit results starting at offset
-::: 'query': fulltext search term
+: 'mountpoints': array of [[#Mount Points|mountpoint ids]] to search (or all if not specified)
-::: 'order_by': key (or array of keys) to order results by, to reverse order use '-key' <i>(but see note below)</i>
+: 'include_files': if true, generate files as if get_filename() had been called for each item. In results, a property 'filename' will be added.
-::: 'limit', 'offset': return only limit results starting at offset
-::: 'mountpoints': array of [[#Mount Points|mountpoint ids]] to search (or all if not specified)
-::: 'include_files': if true, generate files as if get_filename() had been called for each item. In results, a property 'filename' will be added.
 <i>NOTE: Since Sugar 0.84 only very few keys are supported ('uid', 'activity', 'activity_id', 'mime_type',  and 'keep', see [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/master/src/carquinyol/indexstore.py#line32 here]). Other keys are ignored so you may get back more results than expected. Results are ordered by timestamp by default. Sort keys are limited, too (none in 0.84, in 0.86 'timestamp' and 'title', see [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/master/src/carquinyol/indexstore.py#line266 here]).</i>