# Service: Orchard Search

An high-availability microservice REST API for handling search requests against Orchard data.

## Consuming ows-search as a consumer

Search requests against Orchard search data should take the following form:

    https://search.theorchard.io/api/v1/[function]?context=CONTEXT_NAME&token=CONTEXT_TOKEN&[OTHER_PARAMS]

## Getting Started

### Docker Installation

1. Git clone repo.
2. Install docker.
3. CD into ows-search folder.
4. Fill in the .env file with the appropriate values.
5. Run `docker compose up web-deploy`
   ≈

### Search Contexts

The search context is a key in the form CONTEXT_NAME that maps to a Context class in ows-search
[`/src/Query/Context/`](https://github.com/theorchard/ows-search/tree/master/src/Query/Context)
in studly caps. `SAMPLE_SEARCH_CONTEXT` would map to the class `SampleSearchContext`.

For example, the `search` context `PUBLIC_CATALOG_MUSIC` maps to the [PublicCatalogMusic](https://github.com/theorchard/ows-search/blob/master/src/Query/Context/Search/PublicCatalogMusic.php)
class. Here in the class, the [`token`](https://github.com/theorchard/ows-search/blob/master/src/Query/Context/Search/PublicCatalogMusic.php#L11)
is stored. The token for a request must match the context for a search to be issued.

Here's an example of a valid search using the PUBLIC_CATALOG_MUSIC token:

    https://search.theorchard.io/api/v1/search?context=PUBLIC_CATALOG_MUSIC&token=6bb78f6577a8&term=test

### Search Functions

#### search

Search is the basic function. It issues a search against the data specified in the Context
class.

    https://search.theorchard.io/api/v1/search?context=PUBLIC_CATALOG_MUSIC&token=6bb78f6577a8&term=test

#### suggest

Suggest allows for prefix searches against the beginning of a word or search term.

    https://search.theorchard.io/api/v1/suggest?context=PUBLIC_CATALOG_MUSIC&token=6bb78f6577a8&term=wal

##### Searching by multiple filters: vendor_id and subaccount_id

- Context name: INSIGHTS_PRODUCT
- Search by single vendor_id or single subaccount_id
  https://search.theorchard.io/api/v1/suggest?context=INSIGHTS_PRODUCT&token=c9047afefcd6&term=wal&filter.vendor_id[]=1234
  https://search.theorchard.io/api/v1/suggest?context=INSIGHTS_PRODUCT&token=c9047afefcd6&term=wal&filter.subaccount_id[]=1234
- Search by multiple vendors or multiple subaccounts
  https://search.theorchard.io/api/v1/suggest?context=INSIGHTS_PRODUCT&token=c9047afefcd6&term=wal&filter.vendor_id[]=1234&filter.vendor_id[]=4567
  https://search.theorchard.io/api/v1/suggest?context=INSIGHTS_PRODUCT&token=c9047afefcd6&term=wal&filter.subaccount_id[]=1234&filter.subaccount_id[]=4567
- Search by vendor_id and subaccount_id both
  https://search.theorchard.io/api/v1/suggest?context=INSIGHTS_PRODUCT&token=c9047afefcd6&term=wal&filter.vendor_id[]=1234&filter.subaccount_id[]=4567

#### browse

Browse allows for sortable category/subcategory faceting of data with no search term specified.

    https://search.theorchard.io/api/v1/browse?context=PUBLIC_CATALOG_MUSIC&token=6bb78f6577a8&filter.genre=Pop

#### item

Item calls are a quick way to get data for a single piece of Orchard data by ID without
needing to hit art_relations. These item calls show limited data and cannot do table joins,
but allow for some data about Orchard items many times faster than a connection and call to
`art_relations` or redshift `dim-*` tables.

Unlike the other calls,

    https://search.theorchard.io/api/v1/item/release/20045?context=OA_RELEASE&token=c9047afefcd6&term=test

#### catalogsuggest

Catalogsugget allows for prefix searches against the beginning of a word or search term.
This will be responsible to fetch data from one or many contexts i.e : `WORKSTATION_PROJECT` and `WORKSTATION_PRODUCT` and return compound result.
To fetch data by vendor_id,

    https://search.theorchard.io/api/v1/catalogsuggest?context=["WORKSTATION_PROJECT","WORKSTATION_PRODUCT"]&token=c9047afefcd6&filter.vendor_id=23094&term=test

To fetch data from `WORKSTATION_PROJECT_SUBACCOUNT` and `WORKSTATION_PRODUCT_SUBACCOUNT` context by subaccount_id,

    https://search.theorchard.io/api/v1/catalogsuggest?context=["WORKSTATION_PROJECT_SUBACCOUNT","WORKSTATION_PRODUCT_SUBACCOUNT"]&token=c9047afefcd6&filter.subaccount_id=3&term=test

#### More Detail on Functions

Learn the specifics of API calls by reading the [Tech design document](https://docs.google.com/a/theorchard.com/document/d/1qY0R9bcqFBVPLUIz0n7RThI0kq7AnSLVaZmca8wKYOg).

### Consuming ows-search via AJAX

Cross-domain AJAX requests are not allowed (CORS and JSONP are not considered viable solutions
at this time). So, the best way to consume the service via AJAX is to modify the HAProxy of
the URL you're calling from to make its `/api/` or `/searchapi/`.

## Creating a New Context

- Make sure the thing is there in cloudsearch-etl
- Add a new context class for the functions you want