saved_search.md

Preface

This document contains preliminary information. The final implementation will certainly be different; the purpose of this document is to outline the usage scenario of saved_search objects. This document will be extended to reflect these changes.

• $am and $um denote URL base parts for AM and UM API calls, e.g. https://am.api.mediapeers.biz/v20140601

1. The SavedSearch model.

looks like this:

<model name="saved_search" system-id="um">
  <field name="system" type="string" kind="static" writable="true" readable="true"/>
  <field name="model" type="string" kind="static" writable="true" readable="true"/>

  <association name="owner" type="belongs_to" class="user" virtual="true" system-id="um" writable="false" />
  <field name="owner_id" type="integer" kind="static" writable="false"/>

  <field name="description" type="string" kind="dynamic"/>
  <field name="filters" type="array" kind="dynamic"/>
</model>

with these fields:

• system: e.g. "am"

• model: eg: "asset"

• description: free text field

• filters: array of search filters, like this:

    [
      [ "", "q", "searchtext"],
      [ "type", "in", [ "foo", "bar", "baz"] ]],
      [ "transcript.description", "matches", "Louis" ],
    ]
  

1a. Filter entries

The general form of a filter entry is

[ <attribute>, <op>, <matches> ]

where

• <attribute> is the attribute name of an attribute to match (except op "q", which ignores this part, since it matches the complete document instead of only a single attribute);
• <op> is the matching operator, like "q", "matches", "eq", "in"; and
• <matches> describe the match values.

Note: The full list of matches still needs to be finalized.

2. REST interface

To save/create/find a saved_search object use the usual REST API on $um/saved_search and $um/saved_searches. For autocompletion purposes use a $um/saved_searches?q=... style call

3. To run a saved search

.. load the object via JS, you should receive an object like this

  {
    system: "am",
    model: "asset"
    filters: [
      [ "", "q", "searchtext"],:
      [ "type", "in", [ "foo", "bar", "baz"] ]],
      [ "transcript.description", "matches", "Louis" ],
    ]
  }

You can send this object, via a POST method, to "$am/assets/search". The URL may contain additional parameters for sorting, pagination, and aggregations (e.g. lahm_stats=1). The server response is identical to the response of "GET $am/assets", with the difference that this response in addtion contains the saved_search object itself.

4. Using the saved_search object with a UI form

You need to find a way to integrate saved searches with your UI. That means,

1. have a autocomplete text field with fetches a list of saved searches (of that user)
2. when the user selects a saved search from that list the form must adjust itself to reflect the saved_search objects.
3. when the user fills in the form and then clicks "Save Search" the UI should ask the user for a description and the builds a saved_search object as outlined above and POST it to $um/saved_searches