123456789_123456789_123456789_123456789_123456789_

Module: Redis::Commands::Geo

Relationships & Source Files
Extension / Inclusion / Inheritance Descendants
Included In:
::Redis, ::Redis::Commands, ::Redis::MultiConnection, ::Redis::PipelinedConnection
Defined in: lib/redis/commands/geo.rb

Instance Method Summary

Instance Method Details

#_geoarguments(*args, options: nil, sort: nil, count: nil, count_any: false) (private)

[ GitHub ] 

  


# File 'lib/redis/commands/geo.rb', line 175



def _geoarguments(*args, options: nil, sort: nil, count: nil, count_any: false)
  args << sort if sort
  if count
    args << 'COUNT' << Integer(count)
    args << 'ANY' if count_any
  end
  args.concat(Array(options))
  args
end


  








  

    #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)
—    
    don't update already existing elements, always add new ones (since ::Redis 6.2)
    
  
    • 
  
  • 
    xx
    (Boolean)
—    
    only update elements that already exist, never add new ones (since ::Redis 6.2)
    
  
    • 
  
  • 
    ch
    (Boolean)
—    
    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)
  
    • 





  [ GitHub ]


  

  


# 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.
    
  
    • 





  [ GitHub ]


  

  


# 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
    
  
    • 





  [ GitHub ]


  

  


# 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
    
  
    • 





  [ GitHub ]


  

  


# 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
    
  
    • 





  [ GitHub ]


  

  


# 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
    
  
    • 





  [ GitHub ]


  

  


# 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)
—    
    use the position of the given existing member as the center
    
  
    • 
  
  • 
    fromlonlat
    (Array<Numeric>)
—    
    a [longitude, latitude] pair used as the center
    
  
    • 
  
  • 
    byradius
    (Array)
—    
    a [radius, unit] pair where unit is one of 'm', 'km', 'ft', 'mi'
    
  
    • 
  
  • 
    bybox
    (Array)
—    
    a [width, height, unit] triple where unit is one of 'm', 'km', 'ft', 'mi'
    
  
    • 
  
  • 
    sort
    ('asc', 'desc')
—    
    sort returned items from the nearest to the farthest, or vice versa
    
  
    • 
  
  • 
    count
    (Integer)
—    
    limit the results to the first N matching items
    
  
    • 
  
  • 
    count_any
    (Boolean)
—    
    return as soon as enough matches are found (only with count)
    
  
    • 
  
  • 
    withcoord
    (Boolean)
—    
    also return the longitude and latitude of matching items
    
  
    • 
  
  • 
    withdist
    (Boolean)
—    
    also return the distance from the center point
    
  
    • 
  
  • 
    withhash
    (Boolean)
—    
    also return the raw geohash-encoded sorted set score of the item
    
  
    • 



Returns:


    
  
  • 
    (Array<String>)
—    
    may be changed with WITH* flags
    
  
    • 





  [ GitHub ]


  

  


# 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)
—    
    use the position of the given existing member as the center
    
  
    • 
  
  • 
    fromlonlat
    (Array<Numeric>)
—    
    a [longitude, latitude] pair used as the center
    
  
    • 
  
  • 
    byradius
    (Array)
—    
    a [radius, unit] pair where unit is one of 'm', 'km', 'ft', 'mi'
    
  
    • 
  
  • 
    bybox
    (Array)
—    
    a [width, height, unit] triple where unit is one of 'm', 'km', 'ft', 'mi'
    
  
    • 
  
  • 
    sort
    ('asc', 'desc')
—    
    sort returned items from the nearest to the farthest, or vice versa
    
  
    • 
  
  • 
    count
    (Integer)
—    
    limit the results to the first N matching items
    
  
    • 
  
  • 
    count_any
    (Boolean)
—    
    return as soon as enough matches are found (only with count)
    
  
    • 
  
  • 
    storedist
    (Boolean)
—    
    store the distance from the center point as the score
    
  
    • 



Returns:


    
  
  • 
    (Integer)
—    
    number of elements stored in the destination key
    
  
    • 





  [ GitHub ]


  

  


# 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