search/product_search_python/README

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