Merge pull request #31 from ascribe/update-metadata-documentation

update documenation

Author: rhsimplex

docs/source/searches.rst

@@ -44,22 +44,26 @@ The result is a list of hits:
     [
      {'dist': 0.0,
       'id': u'AVM37oZq0osmmAxpPvx7',
+      'metadata': None,
       'path': u'https://pixabay.com/static/uploads/photo/2012/11/28/08/56/mona-lisa-67506_960_720.jpg',
       'score': 7.937254},
      {'dist': 0.22095170140933634,
       'id': u'AVM37nMg0osmmAxpPvx6',
+      'metadata': None,
       'path': u'https://upload.wikimedia.org/wikipedia/commons/thumb/e/ec/Mona_Lisa,_by_Leonardo_da_Vinci,_from_C2RMF_retouched.jpg/687px-Mona_Lisa,_by_Leonardo_da_Vinci,_from_C2RMF_retouched.jpg',
       'score': 0.28797293},
      {'dist': 0.42557196987336648,
       'id': u'AVM37p530osmmAxpPvx9',
+      'metadata': None,
       'path': u'https://c2.staticflickr.com/8/7158/6814444991_08d82de57e_z.jpg',
       'score': 0.0499953}
     ]
 
 ``dist`` is the normalized distance, like we computed above. Hence, lower numbers
 are better with ``0.0`` being a perfect match. ``id`` is an identifier assigned by
 the database. ``score`` is computed by Elasticsearch, and higher numbers are
-better here. ``path`` is the original path (url or file path).
+better here. ``path`` is the original path (url or file path). ``metadata`` is
+an optional field used for storing extra information about the image (see below).
 
 Notice all three Mona Lisa images appear in the results, with the identical
 image being a perfect (``'dist': 0.0``) match. If we search instead for the
@@ -76,6 +80,7 @@ You get:
     [
      {'dist': 0.0,
       'id': u'AVMyXQFw0osmmAxpPvxz',
+      'metadata': None,
       'path': u'https://upload.wikimedia.org/wikipedia/commons/e/e0/Caravaggio_-_Cena_in_Emmaus.jpg',
       'score': 7.937254}
     ]
@@ -97,10 +102,12 @@ Which now returns only the unmodified, catless Mona Lisas:
     [
      {'dist': 0.0,
       'id': u'AVMyXOz30osmmAxpPvxy',
+      'metadata': None,
       'path': u'https://pixabay.com/static/uploads/photo/2012/11/28/08/56/mona-lisa-67506_960_720.jpg',
       'score': 7.937254},
      {'dist': 0.23889600350807427,
       'id': u'AVMyXMpV0osmmAxpPvxx',
+      'metadata': None,
       'path': u'https://upload.wikimedia.org/wikipedia/commons/thumb/e/ec/Mona_Lisa,_by_Leonardo_da_Vinci,_from_C2RMF_retouched.jpg/687px-Mona_Lisa,_by_Leonardo_da_Vinci,_from_C2RMF_retouched.jpg',
       'score': 0.28797293}
     ]
@@ -125,14 +132,17 @@ returns
     [
      {'dist': 0.15454905655638429,
       'id': u'AVM37oZq0osmmAxpPvx7',
+      'metadata': None,
       'path': u'https://pixabay.com/static/uploads/photo/2012/11/28/08/56/mona-lisa-67506_960_720.jpg',
       'score': 1.6818419},
      {'dist': 0.24980626832071956,
       'id': u'AVM37nMg0osmmAxpPvx6',
+      'metadata': None,
       'path': u'https://upload.wikimedia.org/wikipedia/commons/thumb/e/ec/Mona_Lisa,_by_Leonardo_da_Vinci,_from_C2RMF_retouched.jpg/687px-Mona_Lisa,_by_Leonardo_da_Vinci,_from_C2RMF_retouched.jpg',
       'score': 0.16198477},
      {'dist': 0.43387141782958921,
       'id': u'AVM37p530osmmAxpPvx9',
+      'metadata': None,
       'path': u'https://c2.staticflickr.com/8/7158/6814444991_08d82de57e_z.jpg',
       'score': 0.031996995}
     ]
@@ -150,3 +160,47 @@ Searching for this image will return no results, unless you search with
     ses.search_image('http://i.imgur.com/T5AusYd.jpg', all_orientations=True)
 
 Then you get the expected matches.
+
+Adding metadata
+^^^^^^^^^^^^^^^
+Sometimes you want to store information with your images independent of the
+reverse image search functionality.  You can do that with the ``metadata=``
+field in the ``add_image`` function.
+
+Let's add one of the images again, with some extra data:
+
+.. code-block:: python
+
+    ses.add_image('https://c2.staticflickr.com/8/7158/6814444991_08d82de57e_z.jpg', metadata={'things': 'stuff!'})
+
+In general, any JSON-like data should work with ``metadata=``. Now we can search for the image:
+
+.. code-block:: python
+
+    ses.search_image('https://c2.staticflickr.com/8/7158/6814444991_08d82de57e_z.jpg')
+
+Returns our previous results along with a new one:
+
+.. code-block:: python
+
+    [
+     {'dist': 0.0,
+      'id': u'AVYhQYhEDpLcdyATKuy-',
+      'metadata': None,
+      'path': u'https://c2.staticflickr.com/8/7158/6814444991_08d82de57e_z.jpg',
+      'score': 7.64685},
+     {'dist': 0.0,
+      'id': u'AVYhRvoWDpLcdyATKuzE',
+      'metadata': {u'things': u'stuff!'},
+      'path': u'https://c2.staticflickr.com/8/7158/6814444991_08d82de57e_z.jpg',
+      'score': 2.435569},
+      ...
+     ]
+
+Where we can see a little extra info. ``image-match`` doesn't provide anyway to query
+the metadata directly, but the user can use Elasticsearch's QL, for example with:
+
+.. code-block:: python
+
+    ses.es.search('images', body={'query': {'match': {'metadata.things': 'stuff!'}}})
+