Changes

m
→‎Querying: More clarification
Line 189: Line 189:  
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.
 
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 '''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.  
+
The '''properties''' argument is an array of strings. It defines which keys to include in the results. 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.  
    
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 '''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.:
Line 197: Line 197:  
A few specific keys adjust the query:
 
A few specific keys adjust the query:
 
: 'query': fulltext search term
 
: 'query': fulltext search term
: 'order_by': key (or array of keys) to order results by, to reverse order use '-key' <i>(but see note below)</i>
+
: 'order_by': sort key (or array of keys) to order results by, to reverse order use '-key' <i>(but see note below)</i>
 
: 'limit', 'offset': return only limit results starting at offset
 
: 'limit', 'offset': return only limit results starting at offset
 
: 'mountpoints': array of [[#Mount Points|mountpoint ids]] to search (or all if not specified)
 
: '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.
 
: '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>
+
<i>NOTE: In Sugar 0.82 you cannot search for 'uid'. Since Sugar 0.84 only very few keys are supported in the query ('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>
    
You can also retrieve an array of unique values for a field:
 
You can also retrieve an array of unique values for a field:
132

edits