featurebase/client/docs/server-interaction.md

Server Interaction

Pilosa URI

A Pilosa URI has the ${SCHEME}://${HOST}:${PORT} format:

• Scheme: Protocol of the URI. Default: http.
• Host: Hostname or ipv4/ipv6 IP address. Default: localhost.
• Port: Port number. Default: 10101.

All parts of the URI are optional, but at least one of them must be specified. The following are equivalent:

• http://localhost:10101
• http://localhost
• http://:10101
• localhost:10101
• localhost
• :10101

A Pilosa URI is represented by the github.com/pilosa/pilosa/v2/net URI struct. Below are a few ways to create URI objects:

import pnet "github.com/pilosa/pilosa/v2/net"

// create the default URI: http://localhost:10101
uri1 := pnet.DefaultURI()

// create a URI from string address
uri2, err := pnet.NewURIFromAddress("index1.pilosa.com:20202");

// create a URI with the given host and port
uri3, err := pnet.NewURIFromHostPort("index1.pilosa.com", 20202);

Pilosa Client

In order to interact with a Pilosa server, an instance of client.Client should be created. The client is thread-safe and uses a pool of connections to the server, so we recommend creating a single instance of the client and sharing it when necessary.

If the Pilosa server is running at the default address (http://localhost:10101) you can create the client with default options using:

import "github.com/pilosa/pilosa/v2/client"

cli := client.DefaultClient()

To use a custom server address, use the NewClient function:

uri, err := pnet.NewURIFromAddress("http://index1.pilosa.com:15000")
if err != nil {
    // Act on the error
}
cli, err := client.NewClient(uri)

Equivalently:

cli, err := client.NewClient("http://index1.pilosa.com:15000")

If you are running a cluster of Pilosa servers, you can create a Cluster struct that keeps addresses of those servers:

uri1, err := pnet.NewURIFromAddress(":10101")
uri2, err := pnet.NewURIFromAddress(":10110")
uri3, err := pnet.NewURIFromAddress(":10111")
cluster := client.NewClusterWithHost(uri1, uri2, uri3)

// Create a client with the cluster
cli, err := client.NewClient(cluster)

That is equivalent to:

cli, err := client.NewClient([]string{":10101", ":10110", ":10111"})

It is possible to customize the behaviour of the underlying HTTP client by passing ClientOption structs to the NewClient function:

cli, err := client.NewClient(cluster,
    client.OptClientConnectTimeout(1000),  // if can't connect in  a second, close the connection
    client.OptClientSocketTimeout(10000),  // if no response received in 10 seconds, close the connection
    client.OptClientPoolSizePerRoute(3),  // number of connections in the pool per host
    client.OptClientTotalPoolSize(10))   // number of total connections in the pool

Once you create a client, you can create indexes, fields or start sending queries.

Here is how you would create a index and field:

// materialize repository index definition and stargazer field definition initialized before
err := cli.SyncSchema(schema)

You can send queries to a Pilosa server using the Query function of the Client struct:

response, err := cli.Query(field.Row(5));

Server Response

When a query is sent to a Pilosa server, the server either fulfills the query or sends an error message. In the case of an error, a pilosa.Error struct is returned, otherwise a QueryResponse struct is returned.

A QueryResponse struct may contain zero or more results of QueryResult type. You can access all results using the Results function of QueryResponse (which returns a list of QueryResult objects), or you can use the Result method (which returns either the first result or nil if there are no results):

response, err := cli.Query(field.Row(5))
if err != nil {
    // Act on the error
}

// check that there's a result and act on it
result := response.Result()
if result != nil {
    // Act on the result
}

// iterate over all results
for _, result := range response.Results() {
    // Act on the result
}

QueryResult objects contain:

• Row() function to retrieve a row result,
• CountItems() function to retrieve column count per row ID entries returned from TopN queries,
• Count() function to retrieve the number of rows per the given row ID returned from Count queries.
• Value() function to retrieve the result of Min, Max or Sum queries.
• Changed() function returns whether a Set or Clear query changed a column.

row := result.Row()
columns := row.Columns

countItems := result.CountItems()

count := result.Count()

value := result.Value()

changed := result.Changed()

SSL/TLS

Make sure the Pilosa server runs on a TLS address. How To Set Up a Secure Cluster tutorial explains how to do that.

In order to enable TLS support on the client side, the scheme of the address should be explicitly specified as https, e.g.: https://01.pilosa.local:10501

This client library uses the net/http module of Go standard library. You can pass a tls.Config struct in a pilosa.TLSConfig option to the client. If the Pilosa server is using a certificate from a recognized authority, you can use the defaults.

If you are using a self signed certificate, just pass pilosa.TLSConfig(&tls.Config{InsecureSkipVerify: true}) to pilosa.NewClient function:

client, _ := pilosa.NewClient("https://01.pilosa.local:10501", pilosa.TLSConfig(&tls.Config{InsecureSkipVerify: true}))