Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 48 Next »

Important

Depending on the version of HawkSearch used, method of integration, and the presence of data feed files for indexing, you may need to perform indexing as per this article or Using Dashboard API to Rebuild Indexes. Please contact HawkSearch for any clarifications.

Contents

Domains

Hawksearch has three environments available: Development, Test and a load-balanced Production.  When using the search API methods in this document, the following domains can be used to access each environment after your engine has been set-up in that environment.

Development

indexing-dev.hawksearch.net/

Configurations for an engine in this location are maintained in the Hawksearch Workbench at dev.hawksearch.net.

Test

indexing-test.hawksearch.net/

Configurations for an engine in this location are maintained in the Hawksearch Workbench at test.hawksearch.net.

Production

indexingapi-na.hawksearch.com

Configurations for an engine in this location are maintained in the Hawksearch Workbench at https://dashboard-na.hawksearch.com/


Indexing API Methods

Create

This method creates a new index in Hawksearch.  The new index will be empty.  Other methods must be used to populate the index. The methods, IndexItems and DeleteIndexItems are used to add, update and delete items in an index.  The index will not be set to be active until the Set-Current method is called, passing the name of the index.  Each client engine can have multiple indexes, but only 1 current index at a time.

Request

Endpoint

Method

Header Key

api/v2/indexing/create

POST

X-HawkSearch-ApiKey



 Parameters


Name

Data Type

Required

Description

Source or Admin Section

Suffix

String

no

Optional suffix that will be applied to the name of the index to be created.  This may be useful to track the purpose of creating this specific index (i.e. testing a new field).  The string should have no spaces in it.  




 Examples

Example 1.1

Creating index with a suffix

{
    "Suffix": "test-addingcolorfamily"
}


Response

 Structure


Object

Data Type

Always

Description

IndexName

String

Yes

Contains the name of the newly created index.  If the Suffix parameter was populated in the request, it will be the value after the last period.



 Examples

Example 1.2

With a suffix

{
    "IndexName": "myengine.20200123.153931.test-addingcolorfamily"
}

Example 1.3

Without a suffix

{
    "IndexName": "myengine.20200123.153932"
}

Delete Index Item

This method delete the single item from existing index in Hawksearch.  

Request

Endpoint

Method

Header Key

api/v2/indexing/delete

POST

X-HawkSearch-ApiKey



 Parameters


Name

Data Type

Required

Description

Source or Admin Section

IndexName

String

Yes

The name of the index from which item should be deleted


Id

String

Yes

The document id of corresponding item that suppose to be delete




 Examples

Example 2.1

Delete single item from index

{
    "IndexName": "myengine.20200123.153931",

         "Id": "Item_DocId"
}


Response

 Structure

None or Message with Error

Object

Data Type

Description

IndexNames

Array of strings

Each string contains the names of the indexes that exist in the engine.  The most recently created will be listed first.

IndexName

String

Contains the name of the index that is currently active.

Message

String

Will return error message in case if occurs



 Examples

Example 2.2

{
    "Message": "Unable to retrieve item: 'Item_160373'."
}

Delete Index Items

This method deletes multiple items from existing index in Hawksearch.  

Request

Endpoint

Method

Header Key

api/v2/indexing/delete-items

POST

X-HawkSearch-ApiKey



 Parameters


Name

Data Type

Required

Description

Source or Admin Section

IndexName

String

Yes

The name of the index from which item should be deleted


Ids

Array of strings

Yes

Each string contains the document id of an item that suppose to be delete




 Examples

Example 3.1

Delete single item from index

{
    "IndexName": "myengine.20200123.153931",

         "Ids": ["Item_DocId", "Item_Doc2Id"]
}


Response

 Structure

None or Message with Error

Object

Data Type

Description

None or Message with Error





 Examples

Example 3.2

{
    "Message": "Unable to retrieve item: 'Item_160373'."

}

Delete Index

This method delete an existing index in Hawksearch.  

Request

Endpoint

Method

Header Key

api/v2/indexing/delete-index

POST

X-HawkSearch-ApiKey



 Parameters


Name

Data Type

Required

Description

Source or Admin Section

IndexName

String

Yes

The name of the index that should be deleted




 Examples

Example 4.1

Delete index

{
    "IndexName": "myengine.20200123.153931"

}


Response

 Structure

None or Message with Error


Get All Indexes

This method will return all of the indexes that exist for the engine.  

Request

Endpoint

Method

Header Key

api/v2/indexing/

GET

X-HawkSearch-ApiKey



 Parameters


Name

Data Type

Required

Description

Source  or  Admin Section

None






Response

 Structure

The response returns name of the current index.  This Index Name can then be used as a parameter for other method calls. 

Object

Data Type

Description

IndexNames

Array of strings

Each string contains the names of the indexes that exist in the engine.  The most recently created will be listed first.



 Examples

Example 5.1

{

    "IndexNames": [

        "myengine.20200123.081421",

        "myengine.20200123.074248",

        "myengine.20200123.145534",

        "myengine.20200123.114936",

        "myengine.20200123.114657",

        "myengine.20200123.114151"

    ]

}

Get Current Index Name

This method will return the name of the index that is currently being used for search. If there is no “current index,” an error will be returned.

Request

Endpoint

Method

Header Key

api/v2/indexing/current

GET

X-HawkSearch-ApiKey



 Parameters


Name

Data Type

Required

Description

Source or Admin Section

None



  



Response

 Structure

The response returns name of the current index.  This Index Name can then be used as a parameter for other method calls. 

Object

Data Type

Always

Description

IndexName

String

Yes

Contains the name of the index that is currently active.



 Examples

Example 5.1

{
    "IndexName": "myengine.20200123.153932"
}

Index Items

This method adds and updates items and their attributes to a specified index. Attributes must be defined in the Hawksearch Workbench Fields list in order for the attributes to be stored for an object. Once an item is indexed with this method, it will immediately be available in search results, if the modified index is queried.

If an item is sent with a key that matches an existing item, that item will be updated with the attributes being sent. If an item is sent with a new key, that item will be added to the index.

Note: To index hierarchical data, please build the hierarchy using the Hierarchy API and then call the index-items API.

Request

Endpoint

Method

Header Key

api/v2/indexing/index-items

POST

X-HawkSearch-ApiKey



 Parameters


Name

Data Type

Required

Description

Source or Admin Section

IndexName

String

yes

The name of the index to which the item(s) should be added. 

When the index was created, the IndexName was returned in the response from the Create method or the GetCurrentIndex method.


Items

Array of Objects

yes

The Items object will contain all of the attributes that are to be stored for each object. For any object that will be used to supply a facet, the values provided will be the values displayed in the facet on the front-end.

Each item must contain a primary key that matches the primary key defined in the Hawksearch Workbench.

Missing primary key property or passing value that doesn't match the Hawksearch Workbench settings will cause returning error for Item in a Response. The response will return the item in with Status: "Failed" and following error message: "'Primary Key' doesn't exist in the field definition."

Missing correct fields configuration in the Hawksearch Workbench will also cause returning an error for an Item. The response will return the item in with Status: "Failed" and following error message: "There is no fields definition. After adding fields configuration"









 Examples

Example 6.1

{

       "IndexName": "demo.20200221.090452",

       "Items": [

       {

              "id": ["123"],

              "Sku": ["987654"],

              "title": ["Rain Jacket"],

              "price": ["39.99"],

              "saleprice": ["32.99"], "image":["https://www.mysite.com/images/Thumbnail/987654.jpg"],

              "url_detail":["https://www.mysite.com/jackets/mens/987654"],

              "brand" : ["Acme"],

              "color" : ["Orange"]

       },

       {

              "idx": ["987"],

              "Sku": ["123456"],

              "title": ["Down Jacket"],

              "price": ["89.99"],

              "saleprice": ["74.99"], "image":["https://www.mysite.com/images/Thumbnail/123456.jpg"],

              "url_detail":["https://www.mysite.com/jackets/mens/123456"],

              "brand" : ["Acme"],

              "color" : ["Black"]

       }]

}

Response

 Structure


Object

Data Type

Always

Description

Status

 String

Yes


Summary

Array of objects

Yes


> Total

Numeric

Yes


> Succeeded

Numeric

Yes


> Failed

Numeric

Yes


> Warnings

Numeric

Yes


Items

Array of objects

No


> Item




> Status

String



> IgnoredFields

Array


List of fields that were ignored during indexing due to incompatibility with fields configuration


Update Items

This method updates items and their attributes to a specified index. Attributes must be defined in the Hawksearch Workbench Fields list in order for the attributes to be stored for an object. Once an item is updated with this method, it will immediately be available in search results, if the modified index is queried.

This method is only used for existing items and you need to make sure that the item being updated exists in the index. The item will be updated with the attributes being sent. Note that in this method, you can send only those attributes in the request which are required to be updated along with the Primary key and skip the ones which do not require any changes

Request

Endpoint

Method

Header Key

api/v2/indexing/update-items

POST

X-HawkSearch-ApiKey



 Parameters


Name

Data Type

Required

Description

Source or Admin Section

IndexName

String

yes

The name of the index to which the item(s) should be added. 

When the index was created, the IndexName was returned in the response from the Create method or the GetCurrentIndex method.


Items

Array of Objects

yes

The Items object will contain all of the attributes that you need to update for the existing item. For any object that will be used to supply a facet, the values provided will be the values displayed in the facet on the front-end.

Each item must contain a primary key that matches the primary key defined in the Hawksearch Workbench.

Missing primary key property or passing value that doesn't match the Hawksearch Workbench settings will cause returning error for Item in a Response. The response will return the item in with Status: "Failed" and following error message: "'Primary Key' doesn't exist in the field definition."

Missing correct fields configuration in the Hawksearch Workbench will also cause returning an error for an Item. The response will return the item in with Status: "Failed" and following error message: "There is no fields definition. After adding fields configuration"









 Examples

Example 6.1

{

       "IndexName": "demo.20200221.090452",

       "Items": [

       {

              "id": ["123"],

              "brand" : ["Acme"],

              "color" : ["Orange"]

       },

       {

              "idx": ["987"],

              "saleprice": ["74.99"], "image":["https://www.mysite.com/images/Thumbnail/123456.jpg"]

       }]

}

Response

 Structure


Object

Data Type

Always

Description

Status

 String

Yes


Summary

Array of objects

Yes


> Total

Numeric

Yes


> Succeeded

Numeric

Yes


> Failed

Numeric

Yes


> Warnings

Numeric

Yes


Items

Array of objects

No


> Item




> Status

String



> IgnoredFields

Array




Set Current Index

Sets a specified index as the current index.  This will be the index that will be used when calling Hawksearch search methods (documented in a separate document).

Request

Endpoint

Method

Header Key

api/v2/indexing/set-current

POST

X-HawkSearch-ApiKey


 Parameters


Name

Data Type

Required

Description

Source or Admin Section

IndexName

String

yes

Name of an existing, populated index to be set to the current index.  It will immediately be active in the engine for searching against.  




 Examples

Example 7.1

{
    "IndexName": "myengine.20200123.091609"
}

Response

 Structure


Object

Data Type

Always

Description

None





Rebuild All

Rebuilds autocomplete, percolator, learning search and related searches.  

Note

Please note that rebuild-all API does not rebuild the complete index. This is not to be mistaken with full index rebuild process.

Rebuild All only rebuilds the four secondary indices but not the primary index which has the items data. Hence, please follow the steps under FAQ section down below to perform a full index rebuild.


Request

Endpoint

Method

Header Key

api/v2/indexing/rebuild-all

POST

X-HawkSearch-ApiKey


 Parameters


Name

Data Type

Required

Description

Source or Admin Section

IndexName

String

Yes





 Examples

Example 8.1

{
    "IndexName": "myengine.20200123.090452"
}


Response

 Structure


Object

Data Type

Always

Description

None






Rebuild Autocomplete

Rebuilds Autocomplete Categories & Autocomplete Popular Items.  This method is called as part of Rebuild-All.  It is not required that this method be called separately.

Request

Endpoint

Method

Header Key

api/v2/indexing/rebuild-autocomplete

POST

X-HawkSearch-ApiKey


 Parameters


Name

Data Type

Required

Description

Source or Admin Section

IndexName

String

Yes





Response

 Structure


Object

Data Type

Always

Description

None






Rebuild Percolator

Rebuilds Percolator (boost rules & visitor target rules) for Hawksearch.  This method is called as part of Rebuild-All.  It is not required that this method be called separately.

Request

Endpoint

Method

Header Key

api/v2/indexing/rebuild-percolator

POST

X-HawkSearch-ApiKey


 Parameters


Name

Data Type

Required

Description

Source or Admin Section

IndexName

String

Yes





Response

 Structure


Object

Data Type

Always

Description

None






Rebuild Learning Search

Rebuilds Learning Search & Learning Search By Visitor.  This method is called as part of Rebuild-All.  It is not required that this method be called separately.

Request

Endpoint

Method

Header Key

api/v2/indexing/rebuild-learning

POST

X-HawkSearch-ApiKey


 Parameters


Name

Data Type

Required

Description

Source or Admin Section

IndexName

String

Yes





Response

 Structure


Object

Data Type

Always

Description

None






Rebuild Related

Rebuilds Related Searches.  This method is called as part of Rebuild-All.  It is not required that this method be called separately.

Request

Endpoint

Method

Header Key

api/v2/indexing/rebuild-related

POST

X-HawkSearch-ApiKey


 Parameters


Name

Data Type

Required

Description

Source or Admin Section

IndexName

String

Yes





Response

 Structure


Object

Data Type

Always

Description

None





FAQs

Hawksearch v4.0 - Indexing API - What are the basic steps to getting an index up?

This is the full index rebuild process. Please refer to this article for the details - Full v/s Partial Indexing

Create Fields

  1. Establish what fields/attributes need to be in Hawksearch. Consider what needs to be searched, what needs to be displayed on the search results page and what might be needed to use for merchandising. Some examples of fields that could be needed for merchandising: a rating field to sort by top rated; a sales margin to use for featured products.

  2. Create fields in Hawksearch workbench for each field/attribute that will be sent to Hawksearch. Alternatively, these fields can be created using the REST API.

(Optional) Create Facets

  1. Once the fields are created in Hawksearch, Facets can then be created. This step is optional in the sense that it is not required to be done at this time, and can be completed after the data has been initially indexed, but Facets should be created at some point to make for a richer search results page, that is also easier to navigate. 

  2. Consider the expectations of your users and what navigation choices they would expect to have available, and consider what fields of data are available for facet use. 

  3. Facets can be created from the Hawksearch workbench, or through the REST API. 

(Optional) Remove old index

  1. If applicable, delete inactive index using the delete API call

Create Index

  1. Use the 'Create' call documented above to create the empty index. 

  2. NOTE: You are limited to a total of two indexes. If you already have two indexes created, you will need to first delete one before you can create a new index. Please see the 'Delete' call documented above for instructions on how to perform this action. 

(Optional) Build Hierarchy

  1. Use the upsert call to add/update new hierarchies (ref Hierarchy API) to add your hierarchical data for nested facets.

  2. Build the hierarchical data model using the build call.

Index Items

  1. Use the Index-Items call to import data into the Index.

(Optional) Set Current Index

  1. You can choose to set the current index using the relevant call, but it is not required. You can submit the index you would like to search against as part of the search call. However, if you do set the current index - that information does not need to be included in the search call. 

Rebuild All

  1. This final step rebuilds several Hawksearch functions - the autocomplete, percolator, learning search and related searches. 

Method Calls Overview

  1. Delete (for older index)

  2. Create (the new index)

  3. Upsert and Rebuild (the hierarchy)

  4. Index-Items (your products)

  5. Set-Current (the latest index)

  6. Rebuild-All (on the latest index)


More info - Full v/s Partial Indexing - Hawksearch Knowledge Base - Confluence (atlassian.net)

Why do I have to send the index name in every request if I am sending the key?

You will have the flexibility to have multiple indexes stored in Hawksearch. The index name is required to indicate on which index the action should be taken.

  • No labels