mirror of
https://github.com/featurebasedb/featurebase.git
synced 2026-08-28 10:54:59 +00:00
362 lines
10 KiB
Markdown
362 lines
10 KiB
Markdown
+++
|
|
title = "API Reference"
|
|
weight = 10
|
|
nav = []
|
|
+++
|
|
|
|
|
|
## API Reference
|
|
|
|
### List all index schemas
|
|
|
|
`GET /index`
|
|
|
|
Returns the schema of all indexes in JSON.
|
|
|
|
``` request
|
|
curl -XGET localhost:10101/index
|
|
```
|
|
``` response
|
|
{"indexes":[{"name":"user","frames":[{"name":"collab"}]}]}
|
|
```
|
|
|
|
### List index schema
|
|
|
|
`GET /index/<index-name>`
|
|
|
|
Returns the schema of the specified index in JSON.
|
|
|
|
``` request
|
|
curl -XGET localhost:10101/index/user
|
|
```
|
|
``` response
|
|
{"index":{"name":"user"}, "frames":[{"name":"collab"}]}]}
|
|
```
|
|
|
|
### Create index
|
|
|
|
`POST /index/<index-name>`
|
|
|
|
Creates an index with the given name.
|
|
|
|
``` request
|
|
curl -XPOST localhost:10101/index/user
|
|
```
|
|
``` response
|
|
{}
|
|
```
|
|
|
|
### Remove index
|
|
|
|
`DELETE /index/index-name`
|
|
|
|
Removes the given index.
|
|
|
|
``` request
|
|
curl -XDELETE localhost:10101/index/user
|
|
```
|
|
``` response
|
|
{}
|
|
```
|
|
|
|
### Query index
|
|
|
|
`POST /index/<index-name>/query`
|
|
|
|
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", rowID=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 the `columnAttrs` query argument to `true`.
|
|
|
|
The query is executed for all [slices](../data-model/#slice) by default. To use specified slices only, set the `slices` query argument to a comma-separated list of slice indices.
|
|
|
|
``` request
|
|
curl "localhost:10101/index/user/query?columnAttrs=true&slices=0,1" \
|
|
-X POST \
|
|
-d 'Bitmap(frame="language", rowID=5)'
|
|
```
|
|
``` response
|
|
{
|
|
"results":[{"attrs":{},"bits":[100]}],
|
|
"columnAttrs":[{"id":100,"attrs":{"name":"Klingon"}}]
|
|
}
|
|
```
|
|
|
|
By default, all bits and attributes (*for `Bitmap` queries only*) are returned. In order to suppress returning bits, set `excludeBits` query argument to `true`; to suppress returning attributes, set `excludeAttrs` query argument to `true`.
|
|
|
|
### Create frame
|
|
|
|
`POST /index/<index-name>/frame/<frame-name>`
|
|
|
|
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:
|
|
|
|
* `timeQuantum` (string): [Time Quantum](../data-model/#time-quantum) for this frame.
|
|
* `inverseEnabled` (boolean): Enables [the inverted view](../data-model/#inverse) for this frame if `true`.
|
|
* `cacheType` (string): [ranked](../data-model/#ranked) or [LRU](../data-model/#lru) caching on this frame. Default is `lru`.
|
|
* `cacheSize` (int): Number of rows to keep in the cache. Default 50,000.
|
|
* `rangeEnabled` (boolean): Enables range-encoded fields in this frame.
|
|
* `fields` (array): List of range-encoded [fields](../data-model/#bsi-range-encoding).
|
|
|
|
Each individual `field` contains the following:
|
|
|
|
* `name` (string): Field name.
|
|
* `type` (string): Field type, currently only "int" is supported.
|
|
* `min` (int): Minimum value allowed for this field.
|
|
* `max` (int): Maximum value allowed for this field.
|
|
|
|
Integer fields are stored as n-bit range-encoded values. Pilosa supports 63-bit, signed integers with values between `min` and `max`.
|
|
|
|
``` request
|
|
curl localhost:10101/index/user/frame/language \
|
|
-X POST \
|
|
-d '{"options": {"inverseEnabled": true}}'
|
|
```
|
|
``` response
|
|
{}
|
|
```
|
|
|
|
``` request
|
|
curl localhost:10101/index/repository/frame/stats \
|
|
-X POST \
|
|
-d '{"rangeEnabled": true, "fields": [{"name": "pullrequests", "type": "int", "min": 0, "max": 1000000}]}'
|
|
```
|
|
``` response
|
|
{}
|
|
```
|
|
|
|
### Remove frame
|
|
|
|
`DELETE /index/<index-name>/frame/<frame-name>`
|
|
|
|
Removes the given frame.
|
|
|
|
``` request
|
|
curl -XDELETE localhost:10101/index/user/frame/language
|
|
```
|
|
``` response
|
|
{}
|
|
```
|
|
|
|
### Change frame time quantum
|
|
|
|
`PATCH /index/<index-name>/frame/<frame-name>/time-quantum`
|
|
|
|
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
|
|
{}
|
|
```
|
|
|
|
### Create Field
|
|
|
|
`POST /index/<index-name>/frame/<frame-name>/field/<field-name>`
|
|
|
|
Creates a new field to store integer values in the given frame.
|
|
|
|
The request payload is JSON, and it must contain the fields `type`, `min`, `max`.
|
|
* `type` (string): Field type, currently only "int" is supported.
|
|
* `min` (int): Minimum value allowed for this field.
|
|
* `max` (int): Maximum value allowed for this field.
|
|
|
|
``` request
|
|
curl localhost:10101/index/repository/frame/stats/field/pullrequests \
|
|
-X POST \
|
|
-d '{"type": "int", "min": 0, "max": 1000000}'
|
|
```
|
|
``` response
|
|
{}
|
|
```
|
|
|
|
### Create input definition
|
|
|
|
<div class="warning">
|
|
Input definition is deprecated as of v0.9.
|
|
</div>
|
|
|
|
`POST /index/<index-name>/input-definition/<input-definition-name>`
|
|
|
|
Creates an input definition in the given index with the given name.
|
|
|
|
The request payload is JSON, and it must contain the fields `frames` and `fields`. `frames` is an array of frames used within this input definition. Each frame must contain a `name` and may contain the following options:
|
|
|
|
* `timeQuantum` (string): [Time Quantum](../data-model/#time-quantum) for this frame.
|
|
* `inverseEnabled` (boolean): Enables [the inverted view](../data-model/#inverse) for this frame if `true`.
|
|
* `cacheType` (string): [ranked](../data-model/#ranked) or [LRU](../data-model/#lru) caching on this frame. Default is `lru`.
|
|
* `cacheSize` (int): Number of rows to keep in the cache. Default 50,000.
|
|
|
|
The `fields` array contains a series of JSON objects describing how to process each field received in the input data. Each `field` object must contain a `name` which maps to the source JSON field name. One field must be defined at the `primaryKey`. The `primarykey` source field name must equal the column label for the `Index`, and its value must be an unsigned integer which maps directly to a columnID in Pilosa.
|
|
|
|
* `name` (string): Maps the source data field to actions that process the field's corresponding value.
|
|
* `actions` (array): List of actions that will process the field's value.
|
|
|
|
The `action` describes how the field value will be processed. Each `action` may contain:
|
|
|
|
* `frame` (string): The Frame that will contain this action's set bits.
|
|
* `rowid` (int): The action can use this as a pre-defined SetBit rowID. The user is required to ensure this ID does not overlap with other rows in use per frame.
|
|
* `valueDestination` (string): The mapping rule used for this data.
|
|
- `value-to-row`: The value should be an integer and will map directly to a RowID.
|
|
- `single-row-boolean`: If the value is true set a bit using the `rowid`.
|
|
- `mapping`: Map the value to a RowID in the `valueMap`.
|
|
* `valueMap` (object): string and integer pairs used to map field values to RowID's.
|
|
|
|
``` request
|
|
curl localhost:10101/index/user/input-definition/stargazer-input \
|
|
-X POST \
|
|
-d '{
|
|
"frames":[
|
|
{
|
|
"name": "language",
|
|
"options": {"inverseEnabled": true}
|
|
}
|
|
],
|
|
"fields":[
|
|
{
|
|
"name": "repo_id",
|
|
"primaryKey":true
|
|
},
|
|
{
|
|
"name": "language_id",
|
|
"actions":[
|
|
{
|
|
"frame": "language",
|
|
"valueDestination": "mapping",
|
|
"valueMap": {
|
|
"Go": 5,
|
|
"Python": 17,
|
|
"C++": 10
|
|
}
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}'
|
|
```
|
|
``` response
|
|
{}
|
|
```
|
|
|
|
### Get input definition
|
|
|
|
<div class="warning">
|
|
Input definition is deprecated as of v0.9.
|
|
</div>
|
|
|
|
`GET /index/<index-name>/input-definition/<input-definition-name>`
|
|
|
|
Returns the given input definition as JSON.
|
|
|
|
``` request
|
|
curl -XGET localhost:10101/index/user/input-definition/stargazer-input
|
|
```
|
|
``` response
|
|
{"frames":[{"name":"language","options":{"inverseEnabled":true}}],"fields":[{"name":"repo_id","primaryKey":true},{"name":"language_id","actions":[{"frame":"language","valueDestination":"mapping","valueMap":{"Go":5,"Python":17,"C++":10}}]}]}
|
|
```
|
|
|
|
### Remove input definition
|
|
|
|
<div class="warning">
|
|
Input definition is deprecated as of v0.9.
|
|
</div>
|
|
|
|
`DELETE /index/<index-name>/input-definition/<input-definition-name>`
|
|
|
|
Removes the given input definition.
|
|
|
|
``` request
|
|
curl -XDELETE localhost:10101/index/user/input-definition/stargazer-input
|
|
```
|
|
``` response
|
|
{}
|
|
```
|
|
|
|
### Process input data
|
|
|
|
<div class="warning">
|
|
Input definition is deprecated as of v0.9.
|
|
</div>
|
|
|
|
`POST /index/<index-name>/input/<input-definition-name>`
|
|
|
|
Processes the JSON payload using the given input definition.
|
|
|
|
The request payload is a JSON array of objects containing one field for the primary key that corresponds to the column label, and additional fields that will be handled by corresponding actions in the input definition.
|
|
|
|
``` request
|
|
curl localhost:10101/index/user/input/stargazer-input \
|
|
-X POST \
|
|
-d '[{"language_id": "Go", "repo_id": 92274475}]'
|
|
```
|
|
``` response
|
|
{}
|
|
```
|
|
|
|
### List hosts
|
|
|
|
`GET /hosts`
|
|
|
|
Returns the hosts in the cluster.
|
|
|
|
``` request
|
|
curl -XGET localhost:10101/hosts
|
|
```
|
|
``` response
|
|
[{"host":":10101"}]
|
|
```
|
|
|
|
### Get version
|
|
|
|
`GET /version`
|
|
|
|
Returns the version of the Pilosa server.
|
|
|
|
``` request
|
|
curl -XGET localhost:10101/version
|
|
```
|
|
``` response
|
|
{"version":"v0.6.0"}
|
|
```
|
|
|
|
### Recalculate Caches
|
|
|
|
`POST /recalculate-caches`
|
|
|
|
Recalculates the caches on demand. The cache is recalculated every 10
|
|
seconds by default. This endpoint can be used to recalculate the cache
|
|
before the 10 second interval. This should probably only be used in
|
|
integration tests and not in a typical production workflow. Note that
|
|
in a multi-node cluster, the cache is only recalculated on the node
|
|
that receives the request.
|
|
|
|
Response: `204 No Content`
|
|
|