|
| 1 | +.. toctree:: |
| 2 | + :maxdepth: 1 |
| 3 | + :hidden: |
| 4 | + |
| 5 | +Search |
| 6 | +------ |
| 7 | + |
| 8 | +Overview |
| 9 | +~~~~~~~~ |
| 10 | + |
| 11 | +Cloud Search allows you to quickly perform full-text and geospatial searches |
| 12 | +against your data without having to spin up your own instances |
| 13 | +and without the hassle of managing and maintaining a search service. |
| 14 | + |
| 15 | +Cloud Search provides a model for indexing your documents |
| 16 | +that contain structured data, |
| 17 | +with documents and indexes saved to a separate persistent store |
| 18 | +optimized for search operations. |
| 19 | +You can search an index, and organize and present your search results. |
| 20 | +The API supports full text matching on string fields |
| 21 | +and allows you to index any number of documents in any number of indexes. |
| 22 | + |
| 23 | +Indexes |
| 24 | +~~~~~~~ |
| 25 | + |
| 26 | +Here's an example of how you might deal with indexes:: |
| 27 | + |
| 28 | + >>> from gcloud import search |
| 29 | + >>> client = searhc.Client() |
| 30 | + |
| 31 | + >>> # List all indexes in your project |
| 32 | + >>> for index in client.list_indexes(): |
| 33 | + ... print index |
| 34 | + |
| 35 | + >>> # Create a new index |
| 36 | + >>> new_index = client.project('index-id-here') |
| 37 | + >>> new_index.name = 'My new index' |
| 38 | + >>> new_index.create() |
| 39 | + |
| 40 | + >>> # Update an existing index |
| 41 | + >>> index = client.get_index('existing-index-id') |
| 42 | + >>> print index |
| 43 | + <Index: Existing Index (existing-index-id)> |
| 44 | + >>> index.name = 'Modified name' |
| 45 | + >>> index.update() |
| 46 | + >>> print index |
| 47 | + <Index: Modified name (existing-index-id)> |
| 48 | + |
| 49 | + >>> # Delete an index |
| 50 | + >>> index = client.get_index('existing-index-id') |
| 51 | + >>> index.delete() |
| 52 | + |
| 53 | +Documents |
| 54 | +~~~~~~~~~ |
| 55 | + |
| 56 | +Documents are the things that you search for. |
| 57 | +The typical process is to create a document, add fields to the document, |
| 58 | +and then add the document to an index to be searched for later. |
| 59 | + |
| 60 | +Here's an example of how you might deal with documents:: |
| 61 | + |
| 62 | + >>> from gcloud import search |
| 63 | + >>> client = search.Client() |
| 64 | + |
| 65 | + >>> # Create a document |
| 66 | + >>> document = search.Document('document-id') |
| 67 | + |
| 68 | + >>> # Add a field to the document |
| 69 | + >>> field = search.Field('fieldname') |
| 70 | + >>> field.add_value('string') |
| 71 | + >>> document.add_field(field) |
| 72 | + |
| 73 | + >>> # Add the document to an index |
| 74 | + >>> index = client.get_index('existing-index-id') |
| 75 | + >>> index.add_document(document) |
| 76 | + |
| 77 | +Fields |
| 78 | +~~~~~~ |
| 79 | + |
| 80 | +Fields belong to documents and are the data that actually gets searched. |
| 81 | +Each field can have multiple values |
| 82 | +There are three different types of tokenization forms for string values: |
| 83 | + |
| 84 | +- **Atom** means "don't tokenize this string", treat it as one thing to |
| 85 | + compare against. |
| 86 | +- **Text** means "treat this string as normal text" and split words apart |
| 87 | + to be compared against. |
| 88 | +- **HTML** means "treat this string as HTML", understanding the tags, and |
| 89 | + treating the rest of the content like Text. |
| 90 | + |
| 91 | +You can set this using the ``tokenization`` paramater when adding a field |
| 92 | +value:: |
| 93 | + |
| 94 | + >>> from gcloud import search |
| 95 | + >>> document = search.Document('document-id') |
| 96 | + >>> document.add_field(search.Field('field-name', values=[ |
| 97 | + ... search.Value('britney spears', tokenization='atom'), |
| 98 | + ... search.Value('<h1>Britney Spears</h1>', tokenization='html'), |
| 99 | + ... ])) |
| 100 | + |
| 101 | +Searching |
| 102 | +~~~~~~~~~ |
| 103 | + |
| 104 | +Once you have indexes full of documents, you can search through them by |
| 105 | +issuing a search query. |
| 106 | + |
| 107 | +Here's a simple example of how you might start searching:: |
| 108 | + |
| 109 | + >>> from gcloud import search |
| 110 | + >>> client = search.Client() |
| 111 | + |
| 112 | + >>> index = client.get_index('existing-index-id') |
| 113 | + >>> query = search.Query('britney spears') |
| 114 | + >>> matching = index.search(query) |
| 115 | + >>> for match in matching: |
| 116 | + ... print match |
| 117 | + |
| 118 | +By default, all queries are sorted by the ``rank`` value you set |
| 119 | +when the documented was created. |
| 120 | +If you want to sort differently, use the ``order_by`` parameter:: |
| 121 | + |
| 122 | + >>> from gcloud import search |
| 123 | + >>> query = search.Query('britney spears', order_by=['field1', '-field2']) |
| 124 | + |
| 125 | +Note that the ``-`` character before ``field2`` means that |
| 126 | +this query will be sorted ascending by ``field`` |
| 127 | +and then descending by ``field2``. |
| 128 | + |
| 129 | +If you want only want certain fields to be returned in the match, |
| 130 | +you can use the ``fields`` paramater:: |
| 131 | + |
| 132 | + >>> from gcloud import search |
| 133 | + >>> query = search.Query('britney spears', fields=['field1', 'field2']) |
| 134 | + |
0 commit comments