CONCEPTS.md

   1 # High Level Concepts\r
   2 \r
   3 The _Search Data Service_ is built around a set of fundamental concepts and building blocks, which we will describe at a high level here.\r
   4 \r
   5 We will explore in more detail how to express these concepts when interacting with the _Search Data Service_ in more concrete terms in the section on API syntax.\r
   6 \r
   7 ## Index\r
   8 An _Index_ can be thought of as a collection of _Documents_, and represents the largest granularity of data grouping in the store.\r
   9 \r
  10 Multiple _Indexes_ may be defined within the document store in order to segregate data that is different enough that we don't typically want to consider them within the same contexts.\r
  11 \r
  12 For details regarding how to manipulate document indexes, please refer to the [Index API](./INDEXES.md) page.\r
  13 \r
  14 ## Document\r
  15 _Documents_ are the things we are putting into our Document Store (go figure!) and represent the smallest independent unit of data with which the document store is concerned.\r
  16 \r
  17 Documents are composed of _Fields_ which contain the documents' data.\r
  18 \r
  19 ### Document Fields\r
  20 _Fields_ represent the individual bits of data which make up a document and can be thought of as describing the _structure_ of the document.\r
  21 _Fields_ have a number of attributes associated with them which instruct the _Search Service_ about how to treat the data which they contain.\r
  22 \r
  23 \r
  24 | Field           | Description                                                              | \r
  25 | :-------------- | :----------------------------------------------------------------------- |\r
  26 | name            | Identifier for the field                                                 | \r
  27 | searchable      | Indicates whether or not this field should be indexed.  Defaults to true |\r
  28 | search_analyzer | Which analyzer should be used for queries.  Defaults to TBD              |\r
  29 | index_analyzer  | Which analyzer will be used for indexing                                 |\r
  30 \r
  31 For details regarding how to manipulate documents, please refer to the [Document API](./DOCUMENTS.md) page.\r
  32 \r
  33 ## Analysis\r
  34 Field analysis is the process of a taking a _Document_'s fields and breaking them down into tokens that can be used for indexing and querying purposes.  How a document is analyzed has a direct impact on the sort of _Queries_ that we can expect to perform against that data.\r
  35 \r
  36 ### Analyzers\r
  37 An _Analyzer_ can be envisioned as describing a pipeline of operations that a document is run through in the process of persisting it in the document store.  These can be broken down as follows:\r
  38 \r
  39      +--------------------+\r
  40      |    DATA STREAM     |\r
  41      | (ie: the document) |\r
  42      +--------------------+\r
  43                |\r
  44                V\r
  45        \---------------/       \r
  46         \  Character  / -------------- Apply character level transformations on the data stream.\r
  47          \ Filter(s) /\r
  48           \---------/\r
  49                |\r
  50                V\r
  51        +----------------+              \r
  52        | SANITIZED DATA |\r
  53        |     STREAM     |\r
  54        +----------------+\r
  55                |\r
  56                V\r
  57         \-------------/      \r
  58          \ Tokenizer / --------------- Break the data stream into tokens.\r
  59           \---------/\r
  60                |\r
  61                V\r
  62         +--------------+\r
  63         | TOKEN STREAM |\r
  64         +--------------+\r
  65                |\r
  66                V\r
  67      \--------------------/      \r
  68       \  Token Filter(s) / ----------- Apply transformations at the token level (add, remove, or transform tokens)\r
  69        \----------------/\r
  70                |\r
  71                V\r
  72       +-------------------+   \r
  73       | TRANSFORMED TOKEN |\r
  74       |      STREAM       |\r
  75       +-------------------+\r
  76 \r
  77 **Character Filter(s)**\r
  78 The input stream may first be passed through one or more _Character Filters_ which perform transformations in order to clean up or normalize the stream contents (for example, stripping out or transforming HTML tags, converting all characters to lower case, etc)\r
  79 \r
  80 **Tokenizer**\r
  81 The resulting data stream is then tokenized into individual terms.  The choice of tokenizer at this stage determines the rules under which the input stream is split (for example, break the text into terms whenever a whitespace character is encountered).\r
  82 \r
  83 **Token Filter(s)**\r
  84 Each term resulting from the previous stage in the pipeline is then run through any number of _Token Filters_ which may apply various transformations to the terms, such as filtering out certain terms, generating additional terms (for example, adding synonyms for a given term), etc.\r
  85 \r
  86 The set of tokens resulting from the analysis pipeline operations are ultimately used to create indexes in the document store that can later be used to retrieve the data in a variety of ways.\r
  87 \r