Search version 2 (beta)

Note

  • Search version 2 is based on the same principles as search version 1. The SearchDocument has no intervals, joins, groups, metadataGroups, and filter elements as in ItemSearchDocument. Information on how functionality is made accessible in search version 2 can be found in Difference between both searches.

  • Applicable exceptions and new usage concepts are explained on Search version 2 and Migration to search version 2.

  • To use the new search implementation its advisable to revise your metadata structure and clearly separate metadata in generic and timed fields.

    • generic data means all data which is available once and does not repeat itself in the same document, for example: created, owner, accessGroups, admin. This part of the search equals the intervals = generic of search version 1.
    • timed data means all data which is available for specific timespans and repeats and changes itself over multiple timespans. This data has to be sorted in the timespans element of the SearchDocument. This part of the search equals the intervals = timed of search version 1.
    • If a search is performed with timed and generic data, the search equals a search with the element intervals = all of the search version 1.

SearchDocument explained

In this part of the documentation the SearchDocument and all parts are explained to use the search. The explanation is only valid for this search implementation.

  • text: With the text part VidiCore performs an overall search and returns all documents which contains the text value anywhere in the document. If the text value located is in an timed event the return document contains specific timestamps and fields.

  • field: With the field part you search only for generic fields in the index. If a field is embedded in one or multiple group(s) you have to search the field and groups as one field as following pattern: Group/field, Group/subgroup/field. Otherwise you simply search for the field. For examples for a field search with timespans please see Field elements.

  • operator: The operator allows a more complex search approach. One operator contains one operation which specifies which search input must be in one document AND, could be in one document OR and which search input must not be in one document NOT. Also the operator contains a list of fields called field and a list of those operator. For an example with operator please refer to Operator.

  • timespans: Additionally to one or multiple timespans the timespans part contains one operation and a boolean value applyText.

    • timespans: One timespans contains multiple fields, operator and a name. The purpose of one timespans object is to search in one nested index field with specific timestamp. This way you can search, with multiple timespans objects, multiple nested index fields with different timestamps in one document.

      • name: A unique specification for the timespans object for identification, which is essential for highlightíng. If multiple timespans are used in the search, it is necessary to specify a name for each timespans. Otherwise the search will result in an exception and fail.
      • fields: Please enter all fields as explained. For examples for a field search with timespans please see Field elements.
      • operator: For more complex searches, one operator contains one operation and multiple fields. Additionally one operator contains multiple of this kind of operator. Please be aware that an operator in one timespans is not the same operator as the on in the ItemSearchDocument and contains only the previously called elements. For an example with operator refer to Operator.

  • sort: This part sorts all receiving documents by given criteria.

    • field: Please enter the field name as explained previously.
    • order: ascending or descending
    • nested: Specifies if the field is nested (timed data, fields in shapes or fields in files connected to shapes). It is a boolean value which default is false.

  • highlight:

    • prefix: the html start tag, e.g. <em>, <example>
    • suffix: the html end tag, e.g. </em>, </example>
    • field: A list of field names.
    • highlightTimespans: A boolean value, if timed data should be highlighted.
    • matchingOnly: Specifies whether to highlight only fields that contain a search query match.

  • suggestion:

    • maximumSuggestions: Integer of how many suggestion should be returned.
    • accuracy: Double value of how accurate the suggestions should be.

  • autocomplete: Each autocomplete request must contain only one field name, a prefix of the word, and the boolean statement if the request is nested. This version of autocompletion can not work without a prefix.

    • field: Please enter the field as explained previously.
    • text: The beginning of the wanted word.
    • nested: See sort explanation.
    • maximumSuggestions: The maximum of returned suggestions.

  • cursor: The cursor element is a marker to return documents after the given cursor. If the value of the cursor is *, the search returns documents from the beginning and returns a new cursor, which points to the end of the given documents. Use the recieved cursor to continue the search where you stopped.

  • facet: The facet element is used to get a count of matching items and collections. The result can contain a count or a range of the results. This search version can search with timed data as well. For more details look at Faceting.

Text elements

With the text element of the SearchDocument you can perform an overall search with on or multiple values. The text element only performs a search on values of metadata of type string or string-exact.

<SearchDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <text>text-example-value</text>
   <text>text-example-value2</text>
</SearchDocument>

Field elements

If a field is embedded in one or multiple group(s), it has to be searched as one field as following pattern: Group/field, Group/subgroup/field. Otherwise you simply search for the field name.

A search can be performed for only generic, only timed or for both kind of metadata. To combine both generic and timed metadata, the search input has to be sorted in the correct search elements.

Operator

The main operator and the operator in the timespans element are being handled similar. the main operator in the SearchDocument is expected once, while the timespans element contains a list of operator.

Timespans operator

<SearchDocument>
    <timespans>
        <timespans>
            <operator>
                <operation>AND</operation>
                <field>
                    <name>V3_Event_Football/V3_PrimaryParticipant/V3_FirstName</name>
                    <value>Bob</value>
                </field>
            </operator>
            <operator>
                <operation>AND</operation>
                <field>
                    <name>V3_Event_Football/V3_PrimaryParticipant/V3_Position</name>
                    <value>Midfielder</value>
                </field>
            </operator>
        </timespans>
        <operation>AND</operation>
        <applyText>false</applyText>
    </timespans>
</SearchDocument>

Generic operator

<SearchDocument>
    <operator>
        <operation>AND</operation>
        <operator>
            <operation>OR</operation>
            <operator>
                <operation>NOT</operation>
                <field>
                    <name>V3_HomeTeam/V3_Player/V3_FirstName</name>
                    <value>Luke</value>
                </field>
                <field>
                    <name>V3_HomeTeam/V3_Player/V3_Position</name>
                    <value>Forward</value>
                </field>
            </operator>
        <operator>
            <operation>NOT</operation>
                <field>
                    <name>V3_HomeTeam/V3_Player/V3_FirstName</name>
                    <value>Samuel</value>
                </field>
                <field>
                    <name>V3_HomeTeam/V3_Player/V3_Position</name>
                    <value>Forward</value>
                </field>
            </operator>
        </operator>
    </operator>
</SearchDocument>

Highlight

For this highlighting implementation it is necessary to specify the prefix, the suffix, the wanted fields and if matching fields in timespans should be highlighted with specific timestamps. If you add a specific text value, the highlighting will return, which of the given field contains the value.

<SearchDocument>
    <text>text-example-value</text>
    <highlight>
        <prefix><em></prefix>
        <suffix></em></suffix>
        <field>V3_Event_Football/V3_Event_Location_Pitch</field>
        <highlightTimespans>true</highlightTimespans>
    </highlight>
</SearchDocument>

<SearchDocument>
    <timespans>
        <field>
            <name>V3_Event_Football/V3_Event_Location_Pitch</name>
            <value>PASS</value>
        </field>
    </timespans>
    <highlight>
        <prefix><em></prefix>
        <suffix></em></suffix>
        <field>V3_Event_Football/V3_Event_Location_Pitch</field>
        <highlightTimespans>true</highlightTimespans>
    </highlight>
</SearchDocument>

Sorting

If the nested element is true, then the given field is defined as timed data, in shapes or in files connected to shapes. If it is set to false, then the given field is generic in items or collections. The default value for sorting is the field created.

<SearchDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <sort>
        <field>created</field>
        <order>ascending</order>
        <nested>false</nested>
    </sort>
</SearchDocument>

Autocomplete

If the nested element is true, then the given field is defined as timed data, in shapes or in files connected to shapes. If it is set to false, then the given field is generic in items or collections. The text element must be given in the autocomplete request. Without the text element, the request will fail. If the autocomplete request is send without field, the response will contain matching values which begin with the text element.

<SearchDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <autocomplete>
        <text>S</text>
        <field>V3_HomeTeam</field>
        <nested>true</nested>
        <maximumSuggestions>10</maximumSuggestions>
    </autocomplete>
</SearchDocument>

Faceting

For faceting you have to set the nested element to true if the count has to be performed for timespans fields, fields in shapes or fields in files connected to shapes. If set to false, the count will be performed on generic fields of items and collections.

<SearchDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <facet>
        <field>V3_Event_Football/V3_PrimaryParticipant/V3_FirstName</field>
        <exclude>V3_Event_Football/V3_PrimaryParticipant/V3_FirstName</exclude>
        <count>true</count>
        <nested>true</nested>
        <name>V3_Event_Football/V3_PrimaryParticipant/V3_FirstName</name>
    </facet>
    <facet>
        <field>V3_CollectionType</field>
        <exclude>V3_CollectionType</exclude>
        <count>true</count>
        <nested>false</nested>
        <name>V3_CollectionType</name>
    </facet>
</SearchDocument>