Secondary index

The Aerospike Ruby client provides the ability to create and delete secondary indexes.

Creating a Secondary Index

To create a secondary index, invoke Client.create_index. Secondary indexes are created asynchronously, so the method returns before the secondary index propagates to the cluster. As an option, the client can wait for the asynchronous server task to complete.

The following example creates an index idx_ns_set_bin and waits for index creation to complete. The idx_ns_set_bin index is in namespace ns within set set and bin bin:

task = client.create_index('ns', 'set', 'idx_ns_set_bin', 'bin', :numeric)

# to block until the Index is created
task.wait_till_completed
# task is completed successfully

Secondary indexes can only be created once on the server as a combination of Namespace, set, and bin name with either integer or string data types. For example, if you define a secondary index to index bin x that contains integer values, then only records containing bins named x with integer values are indexed. Other records with a bin named x that contain non-integer values are not indexed.

When an index management call is made to any node in the Aerospike Server cluster, the information automatically propagates to the remaining nodes.

Removing a Secondary Index

To remove a secondary index, invoke Client.DropIndex():

client.drop_index('ns', 'set', 'idx_ns_set_bin')

Defining a Query

Use the Aerospike Ruby client library Statement class to define a query against the database.

This example creatis an instance of Statement called stmt:

stmt = Statement.new("ns", "set", ["bin1", "bin2"])

Note

The namespace is required when querying using secondary indexes; however, the set may be optional, depending on the secondary index. You can pass an empty string to omit it.

Filters

To query a secondary index, specify the filters on the query:

stmt.filters << filter1

Filters are created using predefined initializers. The following are the available filter types:

• Filter.Equal(binName, value) — Filter record bin binName containing the specified value.
• Filter.Range(binName, begin, end) — Filter record bin binName containing a value in the specified range.

With a numeric index on bin baz in the namespace ns and set set, add a filter to find all records containing bin baz with values between 0 and 100:

stmt.filters << Filter.Range("baz", 0, 100))

Note

The filter is optional. If a filter is not specified, the scan is performed over the specified set and namespace.

Geospatial Filters

For record bins creating geospatial data in the form of GeoJSON objects, a geospatial index can be created, that supports querying the data using points-within-region and region-contains-point filters:

• Filter.geoWithinGeoJSONRegion(binName, region) — Filter record bin binName containing a GeoJSON object representing a point within the specified GeoJSON region.
• Filter.geoWithinRadius(binName, lon, lat, radius) — Filter record bin binName containing a GeoJSON object representing a point within the specified radius in meter from the lat/lon.
• Filter.geoContainsGeoJSONPoint(binName, point) — Filter record bin binName containing a GeoJSON object representing a polygonal region that contains the specified GeoJSON point.
• Filter.geoContainsPoint(binName, lon, lat) — Filter record bin binName containing a GeoJSON object representing a polygonal region that contains the specified lat/lon.

Note

Geospatial indexes require server version 3.7.0 or newer.

Example:

With a geospatial index on bin loc, find all records where the bin loc represents a GeoJSON region that contains a point with the coordinates (103.91146, 1.30838).

poi = GeoJSON.new({ type: "Point", coordinates: [103.91146, 1.30838] })
stmt.filters << Filter.geoContainsGeoJSONPoint("loc", poi)

Executing Query

To execute the query using #query:

client.query(stmt)

Where stmt is the query to execute.

The return value is an instance of Recordset that provides the ability to iterate over the results of the query.

To execute the query and iterate over the results:

rs = client.query(stmt)

rs.each do |rec|
  # process the record
end