entity-framework/core/modeling/spatial.md
Spatial data represents the physical location and the shape of objects. Many databases provide support for this type of data so it can be indexed and queried alongside other data. Common scenarios include querying for objects within a given distance from a location, or selecting the object whose border contains a given location. EF Core supports mapping to spatial data types using the NetTopologySuite spatial library.
In order to use spatial data with EF Core, you need to install the appropriate supporting NuGet package. Which package you need to install depends on the provider you're using.
| EF Core Provider | Spatial NuGet Package |
|---|---|
| Microsoft.EntityFrameworkCore.SqlServer | Microsoft.EntityFrameworkCore.SqlServer.NetTopologySuite |
| Microsoft.EntityFrameworkCore.Sqlite | Microsoft.EntityFrameworkCore.Sqlite.NetTopologySuite |
| Microsoft.EntityFrameworkCore.InMemory | NetTopologySuite |
| Oracle.EntityFrameworkCore | Oracle.EntityFrameworkCore.NetTopologySuite |
| Npgsql.EntityFrameworkCore.PostgreSQL | Npgsql.EntityFrameworkCore.PostgreSQL.NetTopologySuite |
| Pomelo.EntityFrameworkCore.MySql | Pomelo.EntityFrameworkCore.MySql.NetTopologySuite |
| Devart.Data.MySql.EFCore | Devart.Data.MySql.EFCore.NetTopologySuite |
| Devart.Data.Oracle.EFCore | Devart.Data.Oracle.EFCore.NetTopologySuite |
| Devart.Data.PostgreSql.EFCore | Devart.Data.PostgreSql.EFCore.NetTopologySuite |
| Devart.Data.SQLite.EFCore | Devart.Data.SQLite.EFCore.NetTopologySuite |
| Teradata.EntityFrameworkCore | Teradata.EntityFrameworkCore.NetTopologySuite |
| FileBaseContext | NetTopologySuite |
NetTopologySuite (NTS) is a spatial library for .NET. EF Core enables mapping to spatial data types in the database by using NTS types in your model.
To enable mapping to spatial types via NTS, call the UseNetTopologySuite method on the provider's DbContext options builder. For example, with SQL Server you'd call it like this.
There are several spatial data types. Which type you use depends on the types of shapes you want to allow. Here is the hierarchy of NTS types that you can use for properties in your model. They're located within the NetTopologySuite.Geometries namespace.
[!WARNING] CircularString, CompoundCurve, and CurePolygon aren't supported by NTS.
Using the base Geometry type allows any type of shape to be specified by the property.
Coordinates in NTS are in terms of X and Y values. To represent longitude and latitude, use X for longitude and Y for latitude. Note that this is backwards from the latitude, longitude format in which you typically see these values.
The following entity classes could be used to map to tables in the Wide World Importers sample database.
In LINQ, the NTS methods and properties available as database functions will be translated to SQL. For example, the Distance and Contains methods are translated in the following queries. See your provider's documentation for which methods are supported.
The spatial NuGet packages also enable reverse engineering models with spatial properties, but you need to install the package before running Scaffold-DbContext or dotnet ef dbcontext scaffold. If you don't, you'll receive warnings about not finding type mappings for the columns and the columns will be skipped.
NTS ignores SRID values during operations. It assumes a planar coordinate system. This means that if you specify coordinates in terms of longitude and latitude, some client-evaluated values like distance, length, and area will be in degrees, not meters. For more meaningful values, you first need to project the coordinates to another coordinate system using a library like ProjNet (for GeoAPI).
[!NOTE] Use the newer ProjNet NuGet package, not the older package called ProjNet4GeoAPI.
If an operation is server-evaluated by EF Core via SQL, the result's unit will be determined by the database.
Here is an example of using ProjNet to calculate the distance between two cities.
[!NOTE] 4326 refers to WGS 84, a standard used in GPS and other geographic systems.
Be sure to read your provider's documentation for additional information on working with spatial data.