Module: Redis::Commands::Geo

Included in:
Redis::Commands
Defined in:
lib/redis/commands/geo.rb

Instance Method Summary collapse

Instance Method Details

#geoadd(key, *member, nx: false, xx: false, ch: false) ⇒ Integer

Adds the specified geospatial items (latitude, longitude, name) to the specified key

Parameters:

  • key (String)
  • member (Array) —

    arguemnts for member or members: longitude, latitude, name

  • nx (Boolean) (defaults to: false) —

    don't update already existing elements, always add new ones (since Redis 6.2)

  • xx (Boolean) (defaults to: false) —

    only update elements that already exist, never add new ones (since Redis 6.2)

  • ch (Boolean) (defaults to: false) —

    modify the return value to the number of changed elements (since Redis 6.2)

Returns:

  • (Integer) —

    number of elements added to the sorted set, or changed when ch is set

Raises:

  • (ArgumentError) 


14
15
16
17
18
19
20
21
22
23
 
# File 'lib/redis/commands/geo.rb', line 14

def geoadd(key, *member, nx: false, xx: false, ch: false)
  raise ArgumentError, "can't supply both nx and xx" if nx && xx

  args = [:geoadd, key]
  args << "NX" if nx
  args << "XX" if xx
  args << "CH" if ch
  args.concat(member)
  send_command(args)
end

#geodist(key, member1, member2, unit = 'm') ⇒ String?

Returns the distance between two members of a geospatial index

Parameters:

  • key (String)
  • members (Array<String>)
  • unit ('m', 'km', 'mi', 'ft') (defaults to: 'm')

Returns:

  • (String, nil) —

    returns distance in spefied unit if both members present, nil otherwise.



169
170
171
 
# File 'lib/redis/commands/geo.rb', line 169

def geodist(key, member1, member2, unit = 'm')
  send_command([:geodist, key, member1, member2, unit])
end

#geohash(key, member) ⇒ Array<String, nil>

Returns geohash string representing position for specified members of the specified key.

Parameters:

  • key (String)
  • member (String, Array<String>) —

    one member or array of members

Returns:

  • (Array<String, nil>) —

    returns array containg geohash string if member is present, nil otherwise



30
31
32
 
# File 'lib/redis/commands/geo.rb', line 30

def geohash(key, member)
  send_command([:geohash, key, member])
end

#geopos(key, member) ⇒ Array<Array<String>, nil>

Returns longitude and latitude of members of a geospatial index

Parameters:

  • key (String)
  • member (String, Array<String>) —

    one member or array of members

Returns:

  • (Array<Array<String>, nil>) —

    returns array of elements, where each element is either array of longitude and latitude or nil



72
73
74
 
# File 'lib/redis/commands/geo.rb', line 72

def geopos(key, member)
  send_command([:geopos, key, member])
end

#georadius(*args, **geoptions) ⇒ Array<String>

Query a sorted set representing a geospatial index to fetch members matching a given maximum distance from a point

Parameters:

  • args (Array) —

    key, longitude, latitude, radius, unit(m|km|ft|mi)

  • sort ('asc', 'desc') —

    sort returned items from the nearest to the farthest or the farthest to the nearest relative to the center

  • count (Integer) —

    limit the results to the first N matching items

  • count_any (Boolean) —

    return as soon as enough matches found (only with count, since Redis 6.2)

  • options ('WITHDIST', 'WITHCOORD', 'WITHHASH') —

    to return additional information

Returns:

  • (Array<String>) —

    may be changed with options



44
45
46
47
48
 
# File 'lib/redis/commands/geo.rb', line 44

def georadius(*args, **geoptions)
  geoarguments = _geoarguments(*args, **geoptions)

  send_command([:georadius, *geoarguments])
end

#georadiusbymember(*args, **geoptions) ⇒ Array<String>

Query a sorted set representing a geospatial index to fetch members matching a given maximum distance from an already existing member

Parameters:

  • args (Array) —

    key, member, radius, unit(m|km|ft|mi)

  • sort ('asc', 'desc') —

    sort returned items from the nearest to the farthest or the farthest to the nearest relative to the center

  • count (Integer) —

    limit the results to the first N matching items

  • count_any (Boolean) —

    return as soon as enough matches found (only with count, since Redis 6.2)

  • options ('WITHDIST', 'WITHCOORD', 'WITHHASH') —

    to return additional information

Returns:

  • (Array<String>) —

    may be changed with options



60
61
62
63
64
 
# File 'lib/redis/commands/geo.rb', line 60

def georadiusbymember(*args, **geoptions)
  geoarguments = _geoarguments(*args, **geoptions)

  send_command([:georadiusbymember, *geoarguments])
end

#geosearch(key, frommember: nil, fromlonlat: nil, byradius: nil, bybox: nil, sort: nil, count: nil, count_any: false, withcoord: false, withdist: false, withhash: false) ⇒ Array<String>

Return the members of a geospatial sorted set that are within the borders of the area specified by a given shape, either a circle (BYRADIUS) or a rectangle (BYBOX), starting from a center point given either by member (FROMMEMBER) or by longitude and latitude (FROMLONLAT). Available since Redis 6.2.

Examples:

Search by radius from longitude/latitude

redis.geosearch("Sicily", fromlonlat: [15, 37], byradius: [200, "km"], sort: "asc")
  # => ["Catania", "Palermo"]

Search by box from an existing member, with extras

redis.geosearch("Sicily", frommember: "Catania", bybox: [400, 400, "km"],
                sort: "asc", withcoord: true, withdist: true)
  # => [["Catania", "0.0000", ["15.087...", "37.502..."]], ...]

Parameters:

  • key (String)
  • frommember (String) (defaults to: nil) —

    use the position of the given existing member as the center

  • fromlonlat (Array<Numeric>) (defaults to: nil) —

    a [longitude, latitude] pair used as the center

  • byradius (Array) (defaults to: nil) —

    a [radius, unit] pair where unit is one of 'm', 'km', 'ft', 'mi'

  • bybox (Array) (defaults to: nil) —

    a [width, height, unit] triple where unit is one of 'm', 'km', 'ft', 'mi'

  • sort ('asc', 'desc') (defaults to: nil) —

    sort returned items from the nearest to the farthest, or vice versa

  • count (Integer) (defaults to: nil) —

    limit the results to the first N matching items

  • count_any (Boolean) (defaults to: false) —

    return as soon as enough matches are found (only with count)

  • withcoord (Boolean) (defaults to: false) —

    also return the longitude and latitude of matching items

  • withdist (Boolean) (defaults to: false) —

    also return the distance from the center point

  • withhash (Boolean) (defaults to: false) —

    also return the raw geohash-encoded sorted set score of the item

Returns:

  • (Array<String>) —

    may be changed with WITH* flags



102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
 
# File 'lib/redis/commands/geo.rb', line 102

def geosearch(key, frommember: nil, fromlonlat: nil, byradius: nil, bybox: nil,
              sort: nil, count: nil, count_any: false,
              withcoord: false, withdist: false, withhash: false)
  args = [key]
  args << "FROMMEMBER" << frommember if frommember
  args << "FROMLONLAT" << fromlonlat[0] << fromlonlat[1] if fromlonlat
  args << "BYRADIUS" << byradius[0] << byradius[1] if byradius
  args << "BYBOX" << bybox[0] << bybox[1] << bybox[2] if bybox

  options = []
  options << "WITHCOORD" if withcoord
  options << "WITHDIST" if withdist
  options << "WITHHASH" if withhash

  geoarguments = _geoarguments(*args, sort: sort, count: count, count_any: count_any, options: options)

  send_command([:geosearch, *geoarguments])
end

#geosearchstore(destination, source, frommember: nil, fromlonlat: nil, byradius: nil, bybox: nil, sort: nil, count: nil, count_any: false, storedist: false) ⇒ Integer

Like GEOSEARCH, but stores the result in a destination key. By default the destination is populated with the matching members and their geospatial scores; when STOREDIST is set, the members are stored with their distance from the center point as the score. Available since Redis 6.2.

Examples:

Store the three nearest members

redis.geosearchstore("nearest", "Sicily",
                     fromlonlat: [15, 37], bybox: [400, 400, "km"], sort: "asc", count: 3)
  # => 3

Store distances as scores

redis.geosearchstore("distances", "Sicily",
                     fromlonlat: [15, 37], bybox: [400, 400, "km"], storedist: true)
  # => 3

Parameters:

  • destination (String) —

    key to store the result in

  • source (String) —

    geospatial sorted set to search

  • frommember (String) (defaults to: nil) —

    use the position of the given existing member as the center

  • fromlonlat (Array<Numeric>) (defaults to: nil) —

    a [longitude, latitude] pair used as the center

  • byradius (Array) (defaults to: nil) —

    a [radius, unit] pair where unit is one of 'm', 'km', 'ft', 'mi'

  • bybox (Array) (defaults to: nil) —

    a [width, height, unit] triple where unit is one of 'm', 'km', 'ft', 'mi'

  • sort ('asc', 'desc') (defaults to: nil) —

    sort returned items from the nearest to the farthest, or vice versa

  • count (Integer) (defaults to: nil) —

    limit the results to the first N matching items

  • count_any (Boolean) (defaults to: false) —

    return as soon as enough matches are found (only with count)

  • storedist (Boolean) (defaults to: false) —

    store the distance from the center point as the score

Returns:

  • (Integer) —

    number of elements stored in the destination key



147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
 
# File 'lib/redis/commands/geo.rb', line 147

def geosearchstore(destination, source, frommember: nil, fromlonlat: nil, byradius: nil, bybox: nil,
                   sort: nil, count: nil, count_any: false, storedist: false)
  args = [destination, source]
  args << "FROMMEMBER" << frommember if frommember
  args << "FROMLONLAT" << fromlonlat[0] << fromlonlat[1] if fromlonlat
  args << "BYRADIUS" << byradius[0] << byradius[1] if byradius
  args << "BYBOX" << bybox[0] << bybox[1] << bybox[2] if bybox

  options = []
  options << "STOREDIST" if storedist

  geoarguments = _geoarguments(*args, sort: sort, count: count, count_any: count_any, options: options)

  send_command([:geosearchstore, *geoarguments])
end