featurebase/docs/api-reference.md

+++ title = "API Reference" +++

API Reference

/index

GET

Returns the schema of all indexes in JSON.

Request:

curl -XGET localhost:10101/index

Response:

{"indexes":[{"name":"user","frames":[{"name":"collab"}]}]}

/index/<index-name>

GET

Returns the schema of the specified index in JSON.

Request:

curl -XGET localhost:10101/index/user

Response:

{"index":{"name":"user"}, "frames":[{"name":"collab"}]}]}

POST

Creates an index with the given name.

The request payload is in JSON, and may contain the options field. The options field is a JSON object which may contain the following fields:

• columnLabel (string): column label of the index.

Request:

curl localhost:10101/index/user \
     -X POST \
     -d '{"options": {"columnLabel": "user_id"}}'

Response:

{}

DELETE

Removes the given index.

Request:

curl -XDELETE localhost:10101/index/user

Response:

{}

/index/<index-name>/query

POST

Sends a query to the Pilosa server with the given index. The request body is UTF-8 encoded text and response body is in JSON by default.

Request:

curl localhost:10101/index/user/query \
     -X POST \
     -d 'Bitmap(frame="language", id=5)'

Response:

{"results":[{"attrs":{},"bits":[100]}]}

In order to send protobuf binaries in the request and response, set Content-Type and Accept headers to: application/x-protobuf.

The response doesn't include column attributes by default. To return them, set columnAttrs query argument to true.

The query is executed for all slices by default. To use specified slices only, set slices query argument to a comma-separated list of slice indices.

The time quantum can be specified with the time_granularity. Valid values match those for the time-quantum endpoint.

Request:

curl "localhost:10101/index/user/query?columnAttrs=true&slices=0,1" \
     -X POST \
     -d 'Bitmap(frame="language", id=5)'

Response:

{
  "results":[{"attrs":{},"bits":[100]}],
  "columnAttrs":[{"id":100,"attrs":{"name":"Klingon"}}]
}

/index/<index-name>/time-quantum

PATCH

Changes the time quantum for the given index. This endpoint should be called at most once right after creating a database.

The payload is in JSON with the format: {"timeQuantum": "${TIME_QUANTUM}"}. Valid time quantum values are:

• (Empty string)
• Y: year
• M: month
• D: day
• H: hour
• YM: year and month
• MD: month and day
• DH: day and hour
• YMD: year, month and day
• MDH: month, day and hour
• YMDH: year, month, day and hour

Request:

curl localhost:10101/index/user/time-quantum \
     -X POST \
     -d '{"timeQuantum": "YM"}'

Response:

{}

/index/<index-name>/frame/<frame-name>

POST

Creates a frame in the given index with the given name.

The request payload is in JSON, and may contain the options field. The options field is a JSON object which may contain the following fields:

• rowLabel (string): Row label of the frame.
• timeQuantum (string): [Time Quantum]({{< ref "data-model.md#time-quantum" >}}) for this frame.
• inverseEnabled (boolean): Enables [the inverted view]({{< ref "data-model.md#inverse" >}}) for this frame if true.
• cacheType (string): [ranked]({{< ref "data-model.md#ranked" >}}) or [LRU]({{< ref "data-model.md#lru" >}}) caching on this frame. Default is lru.
• cacheSize (int): Number of rows to keep in the cache. Default 50,000.

Request:

curl localhost:10101/index/user/frame/language \
     -X POST \
     -d '{"options": {"rowLabel": "language_id"}}'

Response:

{}

DELETE

Removes the given frame.

Request:

curl -XDELETE localhost:10101/index/user/frame/language

Response:

{}

/index/<index-name>/frame/<frame-name>/time-quantum

PATCH

Changes the time quantum for the given frame. This endpoint should be called at most once right after creating a frame.

The payload is in JSON with the format: {"timeQuantum": "${TIME_QUANTUM}"}. Valid time quantum values are:

• (Empty string)
• Y: year
• M: month
• D: day
• H: hour
• YM: year and month
• MD: month and day
• DH: day and hour
• YMD: year, month and day
• MDH: month, day and hour
• YMDH: year, month, day and hour

Request:

curl localhost:10101/index/user/frame/language/time-quantum \
     -X POST \
     -d '{"timeQuantum": "YM"}'

Response:

{}

/hosts

GET

Returns the hosts in the cluster.

Request:

curl -XGET localhost:10101/hosts

Response:

[{"host":":10101","internalHost":""}]

/version

GET

Returns the version of the Pilosa server.

Request:

curl -XGET localhost:10101/version

Response:

{"version":"v0.4.0"}