Merge "Reviewed the INFO.yamls and made some updates to ptl etc."
[aai/search-data-service.git] / INDEXES.md
1 # Document Indexes\r
2 \r
3 ## Overview\r
4 An index can be thought of as a collection of _Documents_, and represents the largest granularity of data grouping in the store.\r
5 \r
6 The first step in persisting documents via the _Search Data Service_ is to create the _Index_ into which we will put the documents.\r
7 \r
8 This is where we define the structure of the _Documents_ that we will be storing in our _Index_, including how we want the data in our documents to be analyzed and indexed so that they can be queried for in interesting and useful ways.\r
9 \r
10 ## Syntax\r
11 When we create an _Index_ we need to define the structure of the _Documents_ that we will be storing in it.  Specifically, we must enumerate the _Fields_ that make up the _Document_, the type of data we expect to be stored in each _Field_, and how we want that data to be indexed by the back end document store.\r
12 \r
13 We express this as a JSON structure, enumerating the _Fields_ in our document, where each _Field_ is expressed as a JSON object which conforms to the following schema:\r
14  \r
15     {\r
16         "name":            {"type": "string" },\r
17         "data-type":       {"type": "string" },\r
18         "format":          {"type": "string" },\r
19         "searchable":      {"type": "boolean"},\r
20         "search-analyzer": {"type": "string" },\r
21         "index-analyzer":  {"type": "string" }\r
22     }\r
23     \r
24 Where,\r
25 \r
26     name            = An arbitrary label to assign to the _Index_\r
27     data-type       = One of:  string, date, long, double, boolean, ip, or nested*\r
28     format          = For 'date' type fields, the date format string to use when persisting the field.\r
29     searchable      = true  - field will be indexed,\r
30                       false - field will not be indexed\r
31     search-analyzer = Default analyzer to use for queries if one is not specified as part of the query\r
32                       One of:  whitespace or ngram.\r
33     index-analyser  = Analyzer to use for this field when indexing documents being persisted to the Index\r
34                       One of:  whitespace or ngram.\r
35                     \r
36 \* **Nested** fields:\r
37 If the _data-type_ is specified as _nested_, then this indicates that the contents of the field is itself a set of document fields.  In this case, the _Field_ definition should contain an additional entry named _sub-fields_, which is a JSON array containing the definitions of the sub-fields.  \r
38 \r
39 **Example - A simple document definition which includes a 'date' type field.**\r
40 \r
41 _Take note of the following:_\r
42 * For our 'BirthDate' field, which is a date, we also specify the format string to use when storing the field's contents.\r
43 \r
44     {\r
45         "fields": [\r
46                 {"name": "FirstName", "data-type": "string"},\r
47                 {"name": "LastName", "data-type": "string"},\r
48                 {"name": "BirthDate", "data-type": "date", "format": "MMM d y HH:m:s"}\r
49         ]\r
50     }\r
51 \r
52 \r
53 **Example - An example document definition containing nested sub-fields.**\r
54   \r
55 _Take note of the following:_\r
56 * It is perfectly valid for a nested field to itself contain nested fields\r
57 * For the _Tracks.Title_ field, we are specifying that the _whitespace_ analyzer should be applied for both indexing and queries. \r
58 \r
59     {\r
60         "fields": [\r
61                 {"name": "Album", "data-type": "string"},\r
62                 {"name": "Group", "data-type": "string"},\r
63                 {"name": "Tracks", "data-type": "nested", "sub-fields": [\r
64                         {"name": "Title", "data-type": "string", "index-analyzer": "whitespace", "search-analyzer": "whitespace"},\r
65                         {"name": "Length", "data-type": "long"}\r
66                 ]},\r
67                 {"name": "BandMembers", "data-type": "nested", "sub-fields": [\r
68                         {"name": "FirstName", "data-type": "string"},\r
69                         {"name": "LastName", "data-type": "string"},\r
70                         {"name": "Address", "data-type": "nested", "sub-fields": [\r
71                                 {"name": "Street", "data-type": "string"},\r
72                                 {"name": "City", "data-type": "string"},\r
73                                 {"name": "Country", "data-type": "string"}\r
74                         ]}\r
75                 ]}\r
76         ]\r
77     }\r
78 ## API\r
79 \r
80 ### Create Index\r
81 Define a new _Index_ in the _Search Data Service_.\r
82 \r
83 ---\r
84 **URL**\r
85 \r
86     https://{host}:9509/services/search-data-service/v1/search/indexes/{index}/\r
87 \r
88 **Method** \r
89 \r
90     PUT\r
91 \r
92 **URL Params**\r
93 \r
94     index - The name to assign to the document index we are creating.\r
95 \r
96 **Request Header**\r
97 \r
98     Accept          = application/json\r
99     X-TransactionId = Unique id set by client (for logging purposes)\r
100     X-FromAppId     = Application identifier (for logging purposes)\r
101     Content-Type    = application/json\r
102     \r
103 **Request Payload**\r
104 \r
105     JSON format document structure for this index (see Syntax Section)\r
106 \r
107 **Success Response**\r
108 \r
109     Code:      201\r
110     Header(s): None\r
111     Body:      JSON structure containing the URL for the created Index  \r
112                Example:\r
113                      {"url": "indexes/myindex"}\r
114     \r
115 **Error Response**\r
116 \r
117     400 - Bad Request\r
118     403 - Unauthorized\r
119     500 - Internal Error\r
120 \r
121 ---\r
122 \r
123 \r
124 ### Delete Index\r
125 Remove an existing _Index_ from the _Search Data Service_.  \r
126 Note that this results in the removal of all _Documents_ that are stored in the _Index_ at the time that the DELETE operation occurs.\r
127 \r
128 ---\r
129 **URL**\r
130 \r
131     https://{host}:9509/services/search-data-service/v1/search/indexes/{index}/\r
132 \r
133 **Method** \r
134 \r
135     DELETE\r
136 \r
137 **URL Params**\r
138 \r
139     index - The name to assign to the document index we are creating.\r
140 \r
141 **Request Header**\r
142 \r
143     Accept          = application/json\r
144     X-TransactionId = Unique id set by client (for logging purposes)\r
145     X-FromAppId     = Application identifier (for logging purposes)\r
146     Content-Type    = application/json\r
147 \r
148 **Request Payload**\r
149 \r
150     None\r
151 \r
152 **Success Response**\r
153 \r
154     Code:      201\r
155     Header(s): None\r
156     Body:      JSON structure containing the URL for the created Index  \r
157                Example:\r
158                      {"url": "indexes/myindex"}\r
159     \r
160 **Error Response**\r
161 \r
162     400 - Bad Request\r
163     403 - Unauthorized\r
164     500 - Internal Error\r
165 \r
166 ---\r

© 2017 ONAP. Copyright © The Linux Foundation ®. All Rights Reserved.
The Linux Foundation has registered trademarks and uses trademarks.
For a list of trademarks of The Linux Foundation, please see our Trademark Usage page.
Linux is a registered trademark of Linus Torvalds.
Privacy Policy and Terms of Use