search/product_search_python/static/instrs.html

   1 <?xml version="1.0" encoding="UTF-8" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1 plus MathML 2.0//EN"
   3 "http://www.w3.org/TR/2001/REC-MathML2-20010221/dtd/xhtml-math11-f.dtd">
   4
   5 <html xmlns="http://www.w3.org/1999/xhtml">
   6 <head>
   7   <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
   8   <link rel="stylesheet" type="text/css" href="./css/byword.css"/>
   9   <title>README</title>
  10 </head>
  11
  12 <body>
  13   <div id="wrapper">
  14     <div id="content">
  15 <h1 id="full-textsearchdemoapp:productsearch">Full-Text Search Demo App: Product Search</h1>
  16
  17 <h2 id="introduction">Introduction</h2>
  18
  19 <p>This Python App Engine application illustrates the use of the <a href="https://developers.google.com/appengine/docs/python/search">Full-Text Search
  20 API</a> in a &#8220;Product
  21 Search&#8221; domain with two categories of sample products: <em>books</em> and
  22 <em>hd televisions</em>. This README assumes that you are already familiar with how to
  23 configure and deploy an App Engine app. If not, first see the App Engine
  24 <a href="https://developers.google.com/appengine/docs/python/overview">documentation</a>
  25 and <a href="https://developers.google.com/appengine/docs/python/gettingstarted">Getting Started guide</a>.</p>
  26
  27 <p>This demo app allows users to search product information using full-text search,
  28 and to add reviews with ratings to the products. Search results can be sorted
  29 according to several criteria. In conjunction with listed search results, a
  30 sidebar allows the user to further filter the search results on product rating.
  31 (A product&#8217;s rating is the average of its reviews, so if a product has no
  32 reviews yet, its rating will be 0).</p>
  33
  34 <p>A user does not need to be logged in to search the products, or to add reviews.
  35 A user must be logged in <strong>as an admin of the app to add or modify product
  36 data</strong>. The sidebar admin links are not displayed for non-admin users.</p>
  37
  38 <h2 id="informationaboutrunningtheapplocally">Information About Running the App Locally</h2>
  39
  40 <p>Log in as an app admin to add and modify the app&#8217;s product data.</p>
  41
  42 <p>The app uses XG (cross-group) transactions, which requires the dev_appserver to
  43 be run with the <code>--high_replication</code> flag. E.g., to start up the dev_appserver
  44 from the command line in the project directory (this directory), assuming the
  45 GAE SDK is in your path, do:</p>
  46
  47 <pre><code>dev_appserver.py --high_replication .
  48 </code></pre>
  49
  50 <p>The app is configured to use Python 2.7. On some platforms, it may also be
  51 necessary to have Python 2.7 installed locally when running the dev_appserver.
  52 The app&#8217;s unit tests also require Python 2.7.</p>
  53
  54 <p><strong>Locally, the documents index is not preserved across restarts of the dev app
  55 server</strong>. So, when running locally, you may want to re-initialize the sample
  56 app data upon each restart, as described below.</p>
  57
  58 <p>When running the app locally, not all features of the search API are supported.
  59 So, not all search queries will give the same results during local testing as
  60 when run with the deployed app. As one example, numeric comparison queries are
  61 not currently supported with the dev_appserver. This means that filtering on
  62 product ratings is not supported locally.
  63 Be sure to test on a deployed version of your app as well as locally.</p>
  64
  65 <h2 id="administeringthedeployedapp">Administering the deployed app</h2>
  66
  67 <p>You will need to be logged in as an administrator of the app to add and modify
  68 product data, though not to search products or add reviews. If you want to
  69 remove this restriction, you can edit the <code>login: admin</code> specification in
  70 <code>app.yaml</code>, and remove the <code>@BaseHandler.admin</code> decorators in
  71 <code>admin_handlers.py</code>.</p>
  72
  73 <h2 id="loadingsampledata">Loading Sample Data</h2>
  74
  75 <p>When you first start up your app, you will want to add sample data to it.
  76 Because the <code>dev_appserver</code> does not preserve indexed document data between
  77 restarts, you will probably want to do this <strong>each time you launch the app
  78 locally</strong>. (This is not necessary for the deployed app, which will retain data
  79 between deployments).</p>
  80
  81 <p>Sample product data can be added in two ways. First, sample product data in CSV
  82 format can be added in batch via a link on the app&#8217;s admin page. Batch indexing
  83 of documents is more efficient than adding the documents one at a time. Note
  84 that because the <code>dev_appserver</code> does not preserve indexed document data between
  85 restarts, for consistency <strong>the batch addition of sample data first removes all
  86 existing index and datastore product data</strong>.</p>
  87
  88 <p>The second way to add sample data is via the admin&#8217;s &#8220;Create new product&#8221; link
  89 in the sidebar, which lets an admin add sample products (either &#8220;books&#8221; or
  90 &#8220;hd televisions&#8221;) one at a time.</p>
  91
  92 <h2 id="updatingproductdocumentswithanewaveragerating">Updating product documents with a new average rating</h2>
  93
  94 <p>When a user creates a new review, the average rating for that product is
  95 updated in the datastore. The app may be configured to update the associated
  96 product <code>search.Document</code> at the same time (the default), or do this at a
  97 later time in batch (which is more efficient). See <code>cron.yaml</code> for an example
  98 of how to do this update periodically in batch.</p>
  99
 100 <h2 id="searches">Searches</h2>
 101
 102 <p>Any valid queries can be typed into the search box. This includes simple word
 103 and phrase queries, but you may also submit queries that include references to
 104 specific document fields and use numeric comparators on numeric fields. See the
 105 Search API&#8217;s
 106 <a href="https://developers.google.com/appengine/docs/python/search">documentation</a> for
 107 a description of the query syntax. </p>
 108
 109 <p>Thus, for explanatory purposes, the &#8220;product details&#8221; show all actual
 110 field names of the given product document; you can use this information to
 111 construct queries against those fields. In the same spirit, the raw
 112 query string used for the query is displayed with the search results.</p>
 113
 114 <p>Only product information is searched; product review text is not included in the
 115 search.</p>
 116
 117 <h3 id="someexamplesearches">Some example searches</h3>
 118
 119 <p>Below are some example product queries, which assume the sample data has been loaded.
 120 As discussed above, not all of these queries are supported by the dev_appserver.</p>
 121
 122 <p><code>stories price &lt; 10</code><br/>
 123 <code>price &gt; 10 price &lt; 15</code><br/>
 124 <code>publisher:Vintage</code><br/>
 125 <code>Mega TVs</code><br/>
 126 <code>name:tv1</code><br/>
 127 <code>size &gt; 30</code></p>
 128
 129 <h2 id="geosearch">Geosearch</h2>
 130
 131 <p>This application includes an example of using the Search API to perform
 132 location-based queries. Sample store location data is defined in <code>stores.py</code>,
 133 and is loaded along with the product data. The product details page for a
 134 product allows a search for stores within a given radius of the user&#8217;s current
 135 location. The user&#8217;s location is obtained from the browser.</p>
 136
 137     </div>
 138   </div> <!-- End wrapper -->
 139 </body>
 140 </html>