From 40274fe6b8a3702d05ed8d041e7a659d48eaec16 Mon Sep 17 00:00:00 2001 From: travisturner Date: Mon, 11 Apr 2016 22:28:50 -0500 Subject: [PATCH] update the README file with config and query information --- README.md | 184 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 176 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 4a172735b..333060c54 100644 --- a/README.md +++ b/README.md @@ -5,14 +5,9 @@ Pilosa is a bitmap index database. ## Getting Started -Pilosa uses the new Go 1.5 vendoring experiment. To enable this, you'll need -to export an environment variable in your `.profile`: +Pilosa requires Go 1.6 or greater. -```sh -export GO15VENDOREXPERIMENT=1 -``` - -Then you can download the source by running `go get`: +You can download the source by running `go get`: ```sh $ go get github.com/umbel/pilosa @@ -30,6 +25,167 @@ Now run `pilosa` with the default configuration: pilosa ``` +## Configuration + +You can specify a configuration by setting the `--config` flag when running `pilosa`. + + +```sh +pilosa --config=custom-config-file.cfg +``` + +The config file uses the [TOML](https://github.com/toml-lang/toml) configuration file format, +and should look like: + +``` +data-dir = "/tmp/pil0" +host = "127.0.0.1:15000" + +[cluster] +replicas = 2 + +[[cluster.node]] +host = "127.0.0.1:15000" + +[[cluster.node]] +host = "127.0.0.1:15001" +``` + +The first two configuration options will be unique to each node in the cluster: + +`data-dir`: directory in which data is stored to disk + +`host`: IP and port of the pilosa node + +The remaining configuration options should be the same on every node in the cluster. + +`replicas`: the number of replicas within the cluster + +`[[cluster.node]]`: specifies each node within the cluster + +## Usage + +You can interact with Pilosa via HTTP requests to the host:port on which you have Pilosa running. +The following examples illustrate how to do this using `curl` with a Pilosa cluster running on +127.0.0.1 port 15000. + +Return the version of Pilosa: +```sh +$ curl "http://127.0.0.1:15000/version" +``` + +Return a list of all databases and frames in the index: +```sh +$ curl "http://127.0.0.1:15000/schema" +``` + + +### Queries + +Queries to Pilosa require sending a POST request where the query itself is sent as POST data. +You specify the database on which to perform the query with a URL argument `db=database-name`. + +A query sent to database `exampleDB` will have the following format: + +```sh +$ curl -X POST "http://127.0.0.1:15000/query?db=exampleDB" -d 'Query()' +``` + +The `Query()` object referenced above should be made up of one or more of the query types listed below. +So for example, a SetBit() query would look like this: +```sh +$ curl -X POST "http://127.0.0.1:15000/query?db=exampleDB" -d 'SetBit(id=10, frame="foo", profileID=1)' +``` + +Query results have the format `{"results":[]}`, where `results` is a list of results for each `Query()`. This +means that you can provide multiple `Query()` objects with each HTTP request and `results` will contain +the results of all of the queries. + +```sh +$ curl -X POST "http://127.0.0.1:15000/query?db=exampleDB" -d 'Query() Query() Query()' +``` + +--- +#### SetBit() +``` +SetBit(id=10, frame="foo", profileID=1) +``` +A return value of `{"results":[true]}` indicates that the bit was toggled from 0 to 1. +A return value of `{"results":[false]}` indicates that the bit was already set to 1 and therefore nothing changed. + +--- +#### ClearBit() +``` +ClearBit(id=10, frame="foo", profileID=1) +``` +A return value of `{"results":[true]}` indicates that the bit was toggled from 1 to 0. +A return value of `{"results":[false]}` indicates that the bit was already set to 0 and therefore nothing changed. + +--- +#### SetBitmapAttrs() +``` +SetBitmapAttrs(id=10, frame="foo", category=123, color="blue", happy=true) +``` +Returns `{"results":[null]}` + +--- +#### Bitmap() +``` +Bitmap(id=10, frame="foo") +``` +Returns `{"results":[{"attrs":{"category":123,"color":"blue","happy":true},"bits":[1,2]}]}` where `attrs` are the +attributes set using `SetBitmapAttrs()` and `bits` are the bits set using `SetBit()`. + +--- +#### Union() +``` +Union(Bitmap(id=10, frame="foo"), Bitmap(id=20, frame="foo"))) +``` +Returns a result set similar to that of a `Bitmap()` query, only the `attrs` dictionaly will be empty: `{"results":[{"attrs":{},"bits":[1,2]}]}`. +Note that a `Union()` query can be nested within other queries anywhere that you would otherwise provide a `Bitmap()`. + +--- +#### Intersect() +``` +Intersect(Bitmap(id=10, frame="foo"), Bitmap(id=20, frame="foo"))) +``` +Returns a result set similar to that of a `Bitmap()` query, only the `attrs` dictionaly will be empty: `{"results":[{"attrs":{},"bits":[1]}]}`. +Note that an `Intersect()` query can be nested within other queries anywhere that you would otherwise provide a `Bitmap()`. + +--- +#### Difference() +``` +Difference(Bitmap(id=10, frame="foo"), Bitmap(id=20, frame="foo"))) +``` +`Difference()` represents all of the bits that are set in the first `Bitmap()` but are not set in the second `Bitmap()`. It returns a result set similar to that of a `Bitmap()` query, only the `attrs` dictionaly will be empty: `{"results":[{"attrs":{},"bits":[2]}]}`. +Note that a `Difference()` query can be nested within other queries anywhere that you would otherwise provide a `Bitmap()`. + +--- +#### Count() +``` +Count(Bitmap(id=10, frame="foo")) +``` +Returns the count of the number of bits set in `Bitmap()`: `{"results":[28]}` + +--- +#### Range() +``` +Range(id=10, frame="foo", start="1970-01-01T00:00", end="2000-01-02T03:04") +``` + +--- +#### TopN() +``` +TopN(frame="bar", n=20) +``` +Returns the top 20 Bitmaps from frame `bar`. + +``` +TopN(Bitmap(id=10, frame="foo"), frame="bar", n=20) +``` +Returns the top 20 Bitmaps from `bar` sorted by the count of bits in the intersection with `Bitmap()`. + + ## Development @@ -47,7 +203,19 @@ Then save the dependencies in your project: $ godep save ./... ``` -*Make sure you have set the `GO15VENDOREXPERIMENT` environment variable!* +### Protobuf + +If you update protobuf (pilosa/internal/internal.proto), then you need to run `go generate` +```sh +$ go generate +``` + +### Version + +In order to set the version number, compile Pilosa with the following argument: +```sh +$ go install --ldflags="-X main.Version=1.0.0" +``` [godep]: https://github.com/tools/godep