Skip to content
This repository has been archived by the owner on Nov 9, 2022. It is now read-only.

Place Management

Jump to bottom
isubiker edited this page Nov 11, 2011 · 7 revisions

Place Management

Places tell Corona what JSON keys, XML elements or XML attributes hold your textual content. There are two different types of places that can be managed, anonymous places and named places. Both types can accommodate as many different keys, elements and attributes as necessary.

Anonymous places

Anonymous places tell Corona what JSON keys, XML elements or XML attributes to use when keywords are found in a string query. Let's take the following query as an example: Manufacturing Consent. Without configuring any anonymous places, that query will return documents that contain "Manufacturing" and "Consent" anywhere in the document. Most documents contain metadata and other items that aren't searchable content and in these cases this behavior isn't ideal. Anonymous places enable higher quality search results by targeting the search to the specified items.

Named places

Named places are exactly like anonymous places, except that instead of operating on bare keywords in query strings, they enable fielded queries. Fielded queries are used to specify where a particular keyword should be found in a document. As an example, let's refine the query used in the previous section to only return documents that contain Manufacturing Consent and are from Chomsky. To enable this query, we could create a place named author that points to the location in the document that holds the authors name (more on that below). After configuring the author named place, the query can be satisfied with the string Manufacturing Consent from:Chomsky.

Creating a named place

Before any keys, elements or attributes can be added to a place, it must be created first. This is done by issuing a PUT request to the /manage/place/<place name> endpoint.

  • Request type: PUT
  • Paramaters:
    • mode (optional):
      • textContains (defualt) - A mode of textContains means that the supplied keyword has to be present somewhere in one of the items in the place
      • textEquals - The textEquals mode is a bit more forgiving than equals in that it performs more like a search engine would and less like a string comparison. The textEquals mode ignores punctuation, whitespace and case differences.
      • equals - A mode of equals means that the supplied keyword in the query must be equal to the value of the specified key. In this mode, all whitespace, punctuation, case, etc must match perfectly.
  • Returns:
    • On success a 204 is returned
  • Example:
    • /manage/place/title

Creating the anonymous place

The anonymous place does not need to be explicitly created.

Adding keys, elements, attributes and sub-places

Keys, elements, attributes as well as sub-places are added to a place via individual POST requests. To add multiple items to a place, issue multiple POST requests.

Adding a JSON key to a place

  • Request type: POST
  • Paramaters:
    • key - The JSON key to add into the specified place
    • weight (optional, default: 1) - Configure how important or how heavily this item weighs in the query. The higher the number the more this term will contribute to the score of the document, thus appearing higher in the search results.
    • type (optional):
      • include (default) - When the type of include is specified the key value as well as all content in child objects is included in the place.
      • exclude - Because included items also include child objects, sometimes it's useful to be able to exclude some children.
  • Returns:
    • On success a 204 is returned

Adding a XML element to a place

  • Request type: POST
  • Paramaters:
    • element - The XML element to add into the specified place
    • weight (optional, default: 1) - Configure how important or how heavily this item weighs in the query. The higher the number the more this term will contribute to the score of the document, thus appearing higher in the search results.
    • type (optional):
      • include (default) - When the type of include is specified the element value as well as all content in child objects is included in the place.
      • exclude - Because included items also include child objects, sometimes it's useful to be able to exclude some children.
  • Returns:
    • On success a 204 is returned

Adding a XML attribute to a place

  • Request type: POST
  • Paramaters:
    • element - The XML element that the attribute is attached to
    • attribute - The XML attribute to add into the specified place
    • weight (optional, default: 1) - Configure how important or how heavily this item weighs in the query. The higher the number the more this term will contribute to the score of the document, thus appearing higher in the search results.
  • Returns:
    • On success a 204 is returned

Adding a sub-place to a place

  • Request type: POST
  • Paramaters:
    • place - An existing place that should be inherited by the specified place. Modifying the configuration of the sub-place will be reflected in the configuration of the specified place as well.
  • Returns:
    • On success a 204 is returned

Listing all configured places

To see all of the configured places, make a GET request to:

/manage/places

Removing keys, elements, attributes and sub-places

Removing a JSON key from a place

  • Request type: POST
  • Paramaters:
    • key - The JSON key to remove the specified place
  • Returns:
    • On success a 204 is returned

Removing a XML element from a place

  • Request type: DELETE
  • Paramaters:
    • element - The XML element to delete from the specified place
  • Returns:
    • On success a 204 is returned

Removing a XML attribute from a place

  • Request type: DELETE
  • Paramaters:
    • element - The XML element that the attribute is attached to
    • attribute - The XML attribute to delete from the specified place
  • Returns:
    • On success a 204 is returned

Removing a sub-place from a place

  • Request type: DELETE
  • Paramaters:
    • place - The configured sub-place to be removed from the specified place
  • Returns:
    • On success a 204 is returned

Deleting a place

To completely remove a place, including all of the configured items, issue a DELETE request to the /manage/place/<place name> endpoint.

  • Request type: DELETE
  • Returns:
    • On success a 204 is returned

Discussion

A status code of 201 is perhaps better than a 204 on creation, along with various headers HTTP suggests.

Clone this wiki locally