In this lesson, we're going to discuss the power of MongoDB's geospatial query engine. Specifically, we're going to look at how we can find geospatial documents within a circle on the earth. We're also going to look at how we can find geospatial documents near a point. And finally, we're going to look at how to use 2dsphere indexes and how they relate to geospatial queries. There are times that we have data that contains geospatial information. In the case of mflix, we have a special data set called theaters which is a data set of different theater locations. We can go ahead and look at one example of theater document which looks just like this. As you can see, we have two fields, one being theater_Id, the second being location which is an embedded document where we have address which is a human readable version of the address, and then geo which is a geospatial point. It's handy to structure location this way because the address is easily human readable whereas the geospatial query can be queried by MongoDB in some very useful ways. If we further draw a line to the geo embedded document, you can see that it is formatted in this specific way, where we say type points coordinates and then array of coordinates. This is actually a part of a geospatial standard called GeoJSON. When we use GeoJSON to define a location like this, we can then query for this document using some really powerful query operators. Here's a list of all of the different geospatial query operators. In this lesson, we're going to talk about two of the most common, geoWithin and nearSphere. Let's go ahead and jump into compass so we can easily see these geospatial points. If we go ahead and click the schema tab, we can click analyze, and after a bit of analyzation, we can then scroll down to location and open it up. And you'll see, since we've formatted our points as a GeoJSON point, we had this really nice little map of all the points on a map. Now, here's the best part. We can actually zoom in here, and by holding shift and clicking and dragging, we can actually select a subset or points. This is an excellent way to visualize and play with geo data stored in MongoDB. And the best part is we automatically create a query up here in the filter bar. And as you can see, this query uses the special geoWithin query operator. And as you can probably infer, this query returns all of the points within the circle. But let's go in and break down this query a little bit further. Of course, we're going to say which field we're talking about, which in this case is location.geo because we're using dot notation to query on an embedded field. From here, we can go ahead and use the geoWithin operator. And now since we're talking about locations on our map, we're really talking about points on a sphere, which is why we use the centerSphere operator. And now, this operator takes two parameters passed in via an array, the first being the center of our circle where longitude comes before latitude. And now, I want to point this out. This is longitude and this is latitude. This is backwards of how coordinates are typically specified. And this is a part of the GeoJSON standard, and is the case for some very interesting legacy reasons that I'm not going to get into in this lesson. And then after we specify the center of our circle, the second parameter is the radius of that circle, and that is measured in radians. So, most people aren't super familiar with radius, they're more likely uses something like miles or kilometers. So, here we're going to use the radius of the earth in miles and kilometers in order to convert between the two. So, here we go ahead and take our example radius and paste it in. And then we're going to take that radius and multiply it by the radius of the earth in miles. And now, we can go ahead and print that. And as you can see, it's 430 miles. And when we go look back our query, that's a pretty reasonable estimation. Now, geoWithin supports other operators besides centerSphere. I'm not going to demo these since they function the same as centerSphere. But there's also box, polygon, center, centerSphere, as well as the girdle fashion geometry operator. If you want to learn more about these operators and how they function, I suggest you look at this documentation page, which will be a link to in the notes. The other operator that I want to talk about is nearSphere. And now, this is very similar to geoWithin and centerSphere, but queries executed with this operator will be returned in order by the distance from the center of our sphere. Thus, the near keyword. And so, this is what the syntax looks like for nearSphere. It's pretty similar to geoWithin. But now, we're going to use the dollars sign geometry operator to define the center of our circle. And we also pass in a minDistance and maxDistance determining the area of our circle. We don't actually mean a minDistance since we just want a circle. But you could put in a non-zero value here if you wanted to build a doughnut like shape. Now, it's important to point out here that minDistance and maxDistance are both specified in meters, not in radians like with centerSphere. So let's go and store this query, and then go ahead and execute it. Oh no, what happened here? Well, if we scroll down, we can see that it says, unable to find index for dollar sign geoNear query. And that's because dollar sign nearSphere requires a special index on a GeoJSON field. But fortunately for us, it's very easy for us to create this index using compass. We'll go ahead and go over to indexes, click create index, I'm going to name it geo index. We're going to select the field which in our case is location.geo. We're going to say it's a special 2dsphere index and click create. And just like that, we now have the special 2dsphere index. So now when we go back to our query, we can go ahead and try and run it again. And this time, we see documents. And now, these documents are returned by how far they are away. And so you can see, we have 1000 meters, so one kilometer, from this location which is actually MongoDB's headquarters. And see that there are two theaters within a one kilometer radius. This theater is closer and this theater is a little bit farther away. Let's recap what we learned in this lesson. We saw how we can find documents that have GeoJSON coordinates within a circle on the earth using the centerSphere operator. We also learn how to find documents that are near a points using nearSphere. And finally, we have spent some time discussing which queries require a 2dsphere index and how to build one in compass.
