INTERSECTS
Syntax
INTERSECTS key [CURSOR start] [BUFFER meters] [LIMIT count] [MATCH pattern] [WHERE field min max ...] [WHEREIN field count value [value...] ...] [WHEREEVAL script numargs arg [arg...] ...] [WHEREEVALSHA sha1 numargs arg [arg...] ...] [CLIP] [NOFIELDS] [FENCE] [DETECT what] [COMMANDS which] [COUNT|IDS|OBJECTS|POINTS|BOUNDS|(HASHES precision)] (GET key id)|(BOUNDS minlat minlon maxlat maxlon)|(OBJECT geojson)|(CIRCLE lat lon meters)|(TILE x y z)|(QUADKEY quadkey)|(HASH geohash)|(SECTOR lat lon meters bearing1 bearing2)
Description
INTERSECTS searches a collection for objects that intersect a specified bounding area.
WITHIN and INTERSECTS have identical syntax. The only difference between the two is that WITHIN returns objects that are contained inside an area, and intersects returns objects that are contained or intersects an area.
This command has many options, but at it’s most simplest it may appear like.
INTERSECTS fleet BOUNDS 33.462 -112.268 33.491 -112.245
Above is a search around the rectangle with the southwestern point 33.462,-112.268 and the northeastern point 33.491,-112.245. A list of all objects that intersect the rectangle are returned.
Search Options
Below is a complete list of search options. These options are shared by the NEARBY, WITHIN, INTERSECTS, and SCAN commands.
FENCE
FENCE opens a Geofence.
DETECT
DETECT is available when the FENCE options is specified. It allows for filtering out geofence notifications based on the type. For more information see the Geofence topic.
WHERE
WHERE allows for filtering out results based on field values and object attributes.
Field values
For example:
NEARBY fleet WHERE speed 70 +inf POINT 33.462 -112.268 6000
will return only the objects in the fleet collection that are within the 6 km radius and have a field named speed that is greater than 70.
Multiple WHEREs are concatenated as and clauses. WHERE speed 70 +inf WHERE age -inf 24 would be interpreted as speed is over 70 and age is less than 24.
The default value for a field is always 0. Thus if you do a WHERE on the field speed and an object does not have that field set, the server will pretend that the object does and that the value is Zero.
As of 1.30.0 Tile38 supports more elaborate filter expressions.
SET fleet truck2 FIELD info '{"speed":61,"name":"Tom"}' POINT -112 33
>> {"ok":true}
SCAN fleet WHERE 'info.speed > 45' COUNT
>> {"ok":true,"count":1,"cursor":0}
Object attributes
Using gjson, as of 1.30.0 Tile38 objects can be filtered by object attributes.
# add a complex object
SET fleet truck OBJECT '{"type":"Feature","geometry":{"type":"Point","coordinates":[-112,33]},"properties":{"speed":50},"asdf":"Adsf"}'
>> {"ok":true}
# scan fleet collection and filter
SCAN fleet WHERE properties.speed > 49 IDS
>> {"ok":true,"ids":["truck"],"count":1,"cursor":0}
WHEREIN
WHEREIN is similar to WHERE except that it checks whether the object's field value is in a given list. For examplenearby fleet WHEREIN wheels 3 14 18 22 point 33.462 -112.268 6000 will return only the objects in the 'fleet' collection that are within the 6 km radius and have a field named wheels that is either 14 or 18 or 22.
Multiple WHEREINs are concatenated as and clauses. WHEREIN doors 2 2 5 WHEREIN wheels 3 14 18 22 would be interpreted as doors is either 2 or 5 and wheels is either 14 or 18 or 22.
The default value for a field is always 0. Thus if you do a WHEREIN on the field wheels and an object does not have that field set, the server will pretend that the object does and that the value is Zero.
Note: immediately following the WHEREIN token must be an integer specifying the number of values specified in this clause.
WHEREEVAL
Similar to WHERE except that matching decision is made by Lua script. For example nearby fleet whereeval "return FIELDS.wheels > ARGV[1] or (FIELDS.length * FIELDS.width) > ARGV[2]" 2 8 120 point 33.462 -112.268 6000 will return only the objects in the fleet collection that are within the 6km radius and have a field named wheels that is above 8, or have length and width whose product is greater than 120.
Multiple WHEREEVALs are concatenated as and clauses. See EVAL command for more details. Note that, unlike the EVAL command, WHEREVAL Lua environment (1) does not have KEYS global, and (2) has the FIELDS global with the Lua table of the iterated object's fields.
MATCH
MATCH is similar to WHERE except that it works on the object id instead of fields.nearby fleet match truck* point 33.462 -112.268 6000 will return only the objects in the 'fleet' collection that are within the 6 km radius and have an object id that starts with truck. There can be multiple MATCH options in a single search. The MATCH value is a simple glob pattern.
CURSOR
CURSOR is used to iterate though many objects from the search results. An iteration begins when the CURSOR is set to Zero or not included with the request, and completes when the cursor returned by the server is Zero.
NOFIELDS
NOFIELDS tells the server that you do not want field values returned with the search results.
CLIP
CLIP tells the server to clip intersecting objects by the bounding box area of the search. It can only be used with these area formats: BOUNDS, TILE, QUADKEY, HASH.
LIMIT
LIMIT can be used to limit the number of objects returned for a single search request. If not provide, the default is 100.
BUFFER
Apply a BUFFER around Area Formats to increase the search area by x meters in WITHIN and INTERSECTS searches.
Output Formats
Below is a complete list of output formats. These formats are shared by the NEARBY, WITHIN, INTERSECTS, and SCAN commands.
COUNT - Total object count sent in the response. When LIMIT or CURSOR are provided, COUNT returns the number of results that would otherwise be sent as objects. When LIMIT is not specified, COUNT totals up all items starting from provided CURSOR position (or zero if a cursor is omitted). LIMIT and CURSOR options are ignored
IDS - A list of IDs belonging to the key. Will not return the objects.
OBJECTS - A list of GeoJSON objects.
POINTS - A list of standard latitude, longitude points.
BOUNDS - A list of minimum bounding rectangle.
HASHES - A list of Geohash. Requires a precision of 1 to 22.
Area Formats
Below is a complete list of area formats. These formats are shared by the WITHIN and INTERSECTS commands.
GET - Any object that already exists in the database. For example,
WITHIN poi GET cities tempe
Might be used to search for all object in the poi key that are within the object tempe that belongs to the key cities. Of course, the cities/tempe object must exist in the database.
BOUNDS - A minimum bounding rectangle.
OBJECT - A GeoJSON object.
CIRCLE - A circle with the specified center and radius.
TILE - An XYZ Tile.
QUADKEY - A QuadKey.
HASH - A Geohash.
SECTOR - A Sector.
Fields
The object field values are grouped together in a list per object. Due to the way Tile38 organizes field memory, it's possible to see zero values for fields that have not been set. It's recommended to treat all nonexistent or omitted fields as having the value of zero. Check out this Github issue for more information.