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 ## Configuration
  27
  28 Before you deploy the application, edit `app.yaml` to specify your own app id and version.
  29
  30 In `templates/product.html`, the Google Maps API is accessed.  It does not require an API key, but you are encouraged to use one to monitor your maps usage.  In the <head> element, look for:
  31
  32         src="https://maps.googleapis.com/maps/api/js?sensor=false"
  33
  34 and replace it with something like the following, where `replaceWithYourAPIKey` is your own API key:
  35
  36       src="https://maps.googleapis.com/maps/api/js?sensor=false&amp;key=replaceWithYourAPIKey"
  37
  38 as described [here](https://developers.google.com/maps/documentation/javascript/tutorial#api_key).
  39
  40 ## Information About Running the App Locally
  41
  42 Log in as an app admin to add and modify the app's product data.
  43
  44 The app uses XG (cross-group) transactions, which requires the dev_appserver to
  45 be run with the `--high_replication` flag.  E.g., to start up the dev_appserver
  46 from the command line in the project directory (this directory), assuming the
  47 GAE SDK is in your path, do:
  48
  49     dev_appserver.py --high_replication .
  50
  51 The app is configured to use Python 2.7. On some platforms, it may also be
  52 necessary to have Python 2.7 installed locally when running the dev_appserver.
  53 The app's unit tests also require Python 2.7.
  54
  55 When running the app locally, not all features of the search API are supported.
  56 So, not all search queries may give the same results during local testing as
  57 when run with the deployed app.
  58 Be sure to test on a deployed version of your app as well as locally.
  59
  60 ## Administering the deployed app
  61
  62 You will need to be logged in as an administrator of the app to add and modify
  63 product data, though not to search products or add reviews.  If you want to
  64 remove this restriction, you can edit the `login: admin` specification in
  65 `app.yaml`, and remove the `@BaseHandler.admin` decorators in
  66 `admin_handlers.py`.
  67
  68 ## Loading Sample Data
  69
  70 When you first start up your app, you will want to add sample data to it.
  71
  72 Sample product data can be added in two ways. First, sample product data in CSV
  73 format can be added in batch via a link on the app's admin page. Batch indexing
  74 of documents is more efficient than adding the documents one at a time. For consistency,
  75 **the batch addition of sample data first removes all
  76 existing index and datastore product data**.
  77
  78 The second way to add sample data is via the admin's "Create new product" link
  79 in the sidebar, which lets an admin add sample products (either "books" or
  80 "hd televisions") one at a time.
  81
  82
  83 ## Updating product documents with a new average rating
  84
  85 When a user creates a new review, the average rating for that product is
  86 updated in the datastore.  The app may be configured to update the associated
  87 product `search.Document` at the same time (the default), or do this at a
  88 later time in batch (which is more efficient).  See `cron.yaml` for an example
  89 of how to do this update periodically in batch.
  90
  91 ## Searches
  92
  93 Any valid queries can be typed into the search box.  This includes simple word
  94 and phrase queries, but you may also submit queries that include references to
  95 specific document fields and use numeric comparators on numeric fields.  See the
  96 Search API's
  97 [documentation](https://developers.google.com/appengine/docs/python/search) for
  98 a description of the query syntax.
  99
 100 Thus, for explanatory purposes, the "product details" show all actual
 101 field names of the given product document; you can use this information to
 102 construct queries against those fields. In the same spirit, the raw
 103 query string used for the query is displayed with the search results.
 104
 105 Only product information is searched; product review text is not included in the
 106 search.
 107
 108 ### Some example searches
 109
 110 Below are some example product queries, which assume the sample data has been loaded.
 111 As discussed above, not all of these queries are supported by the dev_appserver.
 112
 113 `stories price < 10`
 114 `price > 10 price < 15`
 115 `publisher:Vintage`
 116 `Mega TVs`
 117 `name:tv1`
 118 `size > 30`
 119
 120 ## Geosearch
 121
 122 This application includes an example of using the Search API to perform
 123 location-based queries.  Sample store location data is defined in `stores.py`,
 124 and is loaded along with the product data.  The product details page for a
 125 product allows a search for stores within a given radius of the user's current
 126 location. The user's location is obtained from the browser.