Merge lp:~pedronis/u1db/document-get-index-w-bool-number into lp:u1db

[Samuele Pedroni]

clarify querying of number() and bool() indexes, values for querying are always strings (atm)

clarify querying of number() and bool() indexes, values for querying are always strings (atm)

[lp:~pedronis/u1db/document-get-index-w-bool-number]

438. By Samuele Pedroni on 2013-05-23

bool() query example

439. By Samuele Pedroni on 2013-05-24

number() example and note

[Stuart Langridge (sil)]

review: Approve

=== modified file 'html-docs/high-level-api.rst'
--- html-docs/high-level-api.rst	2012-09-18 16:25:41 +0000
+++ html-docs/high-level-api.rst	2013-05-24 12:41:26 +0000
@@ -308,8 +308,8 @@
 Querying an index
 ^^^^^^^^^^^^^^^^^
 
-Pass an index key or a tuple of index keys (if the index is on multiple fields)
-to ``get_from_index``; the last index key in each tuple (and *only* the last
+Pass an index key or multiple index keys (if the index is on multiple fields)
+to ``get_from_index``; the last index key (and *only* the last
 one) can end with an asterisk, which matches initial substrings. So, querying
 our ``by-firstname`` index from above:
 
@@ -332,6 +332,30 @@
     >>> assert(jb.doc_id in js)
     >>> assert(jm.doc_id in js)
 
+Index key values used when querying are always strings. If querying an
+index built with ``bool()`` use the values '0' and '1' to query for
+false and true respectively. For an index built with ``number()`` turn
+key number values into strings with the appropriate left zero-padding
+(and note in particular that querying a ``number()`` index with an int
+value, such as ``db.get_from_index('by-number', 9)``, will throw an error).
+
+.. doctest ::
+
+    >>> db = u1db.open('mydb11.u1db', create=True)
+    >>> db.create_index('done', "bool(done)")
+    >>> doc1 = db.create_doc({'task': 'milk', 'done': False, 'hours': 1})
+    >>> doc2 = db.create_doc({'task': 'coding', 'done': True, 'hours': 12})
+    >>> [doc.content['task'] for doc in db.get_from_index('done', '1')]
+    [u'coding']
+    >>> db.create_index('by-hours', "number(hours, 3)")
+    >>> [doc.content['task'] for doc in db.get_from_index('by-hours', '12')]
+    []
+    >>> [doc.content['task'] for doc in db.get_from_index('by-hours', '012')]
+    [u'coding']
+    >>> [doc.content['task'] for doc in db.get_from_index('by-hours', '001')]
+    [u'milk']
+
+
 Index functions
 ^^^^^^^^^^^^^^^
 
@@ -399,4 +423,5 @@
     os.remove(os.path.join(tmp_dir, "mydb8.u1db"))
     os.remove(os.path.join(tmp_dir, "mydb9.u1db"))
     os.remove(os.path.join(tmp_dir, "mydb10.u1db"))
+    os.remove(os.path.join(tmp_dir, "mydb11.u1db"))
     os.rmdir(tmp_dir)