Get Started with Dgraph - Geolocation
We’re overhauling Dgraph’s docs to make them clearer and more approachable. If
you notice any issues during this transition or have suggestions, please
let us know.
find hotels near Golden Gate Bridge, or
find all the tourist location around Golden Gate Park, Dgraph has your back.
First, let’s learn how to represent Geolocation data in Dgraph.
Representing geolocation data
You can represent location data in Dgraph using two ways:- Point location
- Polygonal location
The polygonal fence above represents the city of Delhi, India. This polygonal
fence or the geo-fence is formed by connecting multiple straight-line
boundaries, and they’re collectively represented using an array of location
tuples of format [(latitude, longitude), (latitude, longitude), ...]. Each
tuple pair (2 tuples and 4 coordinates) represents a straight line boundary of
the geo-fence, and a polygonal fence can contain any number of lines.
Let’s start with building a simple San Francisco tourist graph, here’s the graph
model.
The above graph has three entities represented by the nodes:
- City
city node represents the tourist city. Our dataset only contains the city of
San Francisco, and a node in the graph represents it.
- Location
- Location Type
zoo, museum, hotel or a tourist attraction.
The location nodes with geo-coordinates of a hotel also contains their
pricing information.
There are different ways to model the same graph. For instance, the
location type could just be a property or a predicate of the location node,
rather than being a node of its own.
The queries you want to perform or the relationships you like to explore mostly
influence the modeling decisions. The goal of the tutorial isn’t to arrive at
the ideal graph model, but to use a simple dataset to demonstrate the
geolocation capabilities of Dgraph.
For the rest of the tutorial, let’s call the node representing a City as a
city node, and the node representing a Location as a location node, and
the node representing the Location Type as a location type node.
Here’s the relationship between these nodes:
- Every
city nodeis connected to alocation nodevia thehas_locationedge. - Every
location nodeis connected to its node representing alocation typevia thehas_typeedge.
Dgraph allows you to associate one or more types for the nodes using its type
system feature, for now, we’re using nodes without types, we’ll learn about
type system for nodes in a future tutorial. Read more on the DQL
schema to explore type system feature for nodes
Our graph has:
- One blue
city node. We just have one node which represents the city ofSan Francisco. - The green ones are the
locationnodes. We have a total of 13 locations. - The pink nodes represent the
location types. We have four kinds of locations in our dataset:museum,zoo,hotel, andtourist attractions.
geo
type.
Note: Check out the previous tutorial to know more
about data types in Dgraph.
Before we start, please say Hello to Mary, a zoologist who has dedicated her
research for the cause of conserving various bird species.
For the rest of the tutorial, let’s help Mary and her team of zoologists in
their mission to conserving birds.
Enter San Francisco: Hotel booking
Several research projects done by Mary suggested that Flamingos thrive better when there are abundant water bodies for their habitat. Her team got approval for expanding the water source for the Flamingos in the San Francisco Zoo, and her team is ready for a trip to San Francisco with Mary remotely monitoring the progress of the team. Her teammates wish to stay close to theGolden Gate Bridge so that they could
cycle around the Golden gate, enjoy the breeze, and the sunrise every morning.
Let’s help them find a hotel which is within a reasonable distance from the
Golden Gate Bridge, and we’ll do so using Dgraph’s geolocation functions.
Dgraph provides a variety of functions to query geolocation data. To use them,
you have to set the geo index first.
Go to the Schema tab and set the index on the location predicate.
After setting the geo index on the location predicate, you can use Dgraph’s
built-in function near to find the hotels near the Golden gate bridge.
Here is the syntax of the near function:
near(geo-predicate, [long, lat], distance).
The near function matches and
returns all the geo-predicates stored in the database which are within
distance meters of geojson coordinate [long, lat] provided by the user.
Let’s search for hotels within 7KM of from a point on the Golden Gate bridge.
Go to the query tab, paste the query below and click Run.
Wait! The search returns not just the hotels, but also all other locations
within 7 Km from the point coordinate on the Golden Gate Bridge.
Let’s use the @filter function to filter for search results containing only
the hotels. You can visit our third tutorial of the
series to refresh our previous discussions around using the @filter directive.
eq comparator in the filter.
Let’s add a hash index to the loc_type and re-run the query.
Note: Refer to the third tutorial of the series to
learn more about hash index and comparator functions in Dgraph.
The search result still contains nodes representing locations which are not
hotels. That’s because the root query first finds all the location nodes which
are within 7KM from the specified point location, and then it applies the filter
while selectively traversing to the location type nodes.
Only the predicates in the location nodes can be filtered at the root level, and
you cannot filter the location types without traversing to the
location type nodes.
We have the filter to select only the hotels while we traverse the
location type nodes. Can we cascade or bubble up the filter to the root level,
so that, we only have hotels in the final result?
Yes you can! You can do by using the @cascade directive.
The @cascade directive helps you cascade or bubble up the filters applied
to your inner query traversals to the root level nodes, by doing so, we get only
the locations of hotels in our result.
Voila! You can see in the result that, after adding the @cascade directive in
the query, only the locations with type hotel appear in the result.
We have two hotels in the result, and one of them is over their budget of 300300 per
night.
The price information of every hotel is stored in the location nodes along
with their coordinates, hence the filter on the pricing should be at the root
level of the query, not at the level we traverse the location type nodes.
Before you jump onto run the query, don’t forget to add an index on the
price_per_night predicate.
Now we have a hotel well within the budget, and also close to the Golden Gate
Bridge!
Summary
In this tutorial, we learned about geolocation capabilities in Dgraph, and helped Mary’s team book a hotel near Golden bridge. In the next tutorial, we’ll showcase more geolocation functionalities in Dgraph and assist Mary’s team in their quest for conserving Flamingo’s. See you all in the next tutorial. Till then, happy Graphing! Remember to click the “Join our community” button below and subscribe to our newsletter to get the latest tutorial right into your inbox.What’s next?
- Go to Clients to see how to communicate with Dgraph from your app.
- A wider range of queries can also be found in the Query Language reference.
- See Deploy if you wish to run Dgraph in a cluster.
Need help
- Please use discuss.hypermode.com for questions, feature requests, bugs, and discussions.