Improve this page

Store Content API

The Store API allows adding additional content to documents and store such content in the Index Storage.

The Index Storage is designed to put files in volumes much in the way Facebook’s Haystack ¹ works; once there a file enters the storage it can’t really be deleted/modified from the volume, but instead, if a change is needed, a new file blob will be written to the volume. Storage is envisioned to be used when there are files you need to store which you know won’t be changing often or at all.

Assuming there is a PNG file called Lenna.png in the working directory, lets add those to the storage using PUT or UPDATE (if the document already exists) and passing a content type:

PUT /assets/Lenna
Content-Type: image/png
@Lenna.png

And getting it is just a matter of retreiving it using the GET HTTP method:

GET /assets/Lenna
Accept: image/png

Or by visiting the link to it with your web browser: http://localhost:8880/assets/Lenna

Toggle Console Previews
You can enable previews for images in the terminal using the “very-very-very-very” verbose command line option (-vvvvv). Note you a compatible terminal for this feature to work (iTerm2, for example).

Multi-Content Documents

Use PUT or UPDATE with a different Content-Type to add new content to the same document. For example, the following adds a PDF and a JPEG from files called Lenna.pdf and Lenna.jpg, respectively:

UPDATE /assets/Lenna
Content-Type: application/pdf
@Lenna.pdf

This time we also include the .jpg selector as a File Extension:

UPDATE /assets/Lenna.jpg
Content-Type: image/jpeg
@Lenna.jpg

Then you can get either of them requesting the appropriate content type in the Accept header:

GET /assets/Lenna
Accept: application/pdf

Default Content Type

Default Content Type
In Multi-Content Documents, the last content that was stored is the default content type, if none is specified using the Accept header.

GET /assets/Lenna
Accept: *

File Extension

If passing a file extension, the default content type is obtained from the mime.types file (usually in /usr/local/share/xapiand/mime.types).

For example, this will return the content with image/png content type of the document with ID Lenna:

GET /assets/Lenna.png

Or visiting the link to the PNG content with your web browser: http://localhost:8880/assets/Lenna.png

Retrieving Information

You can get the information about the document as usual:

INFO /assets/Lenna

The result (partially shown) has the available content types listed inside data

{
  "docid": 1,
  "data": [
    {
      "content_type": "application/msgpack",
      "type": "inplace"
    },
    {
      "content_type": "image/png",
      "type": "stored",
      "volume": 0,
      "offset": 512,
      "size": "462.7KiB"
    },
    {
      "content_type": "application/pdf",
      "type": "stored",
      "volume": 0,
      "offset": 60063,
      "size": "676.4KiB"
    },
    {
      "content_type": "image/jpeg",
      "type": "stored",
      "volume": 0,
      "offset": 143195,
      "size": "557.6KiB"
    }
  ], ...
}

Removing Content

To remove stored content by storing an empty object:

UPDATE /assets/Lenna
Content-Type: image/jpeg
Content-Length: 0

Note removing content doesn’t actually remove the blob from the volume, it just removes the “link” to it from the document.

---

¹ Finding a needle in Haystack: Facebook’s photo storage.

Back

Next