---
title: "GeoDjango 模型 API"
version: 6.1
locale: zh-hans
source: https://docs.djangoproject.com/zh-hans/6.1/ref/contrib/gis/model-api/
canonical: https://djangodocs.dev/zh-hans/6.1/ref/contrib/gis/model-api/
---
# GeoDjango 模型 API

This document explores the details of the GeoDjango Model API. Throughout this
section, we'll be using the following geographic model of a [ZIP code](https://en.wikipedia.org/wiki/ZIP_code) and
of a [Digital Elevation Model](https://en.wikipedia.org/wiki/Digital_elevation_model) as our examples:

```
from django.contrib.gis.db import models

class Zipcode(models.Model):
    code = models.CharField(max_length=5)
    poly = models.PolygonField()

class Elevation(models.Model):
    name = models.CharField(max_length=100)
    rast = models.RasterField()
```

## 空间字段类型

空间字段包括一系列几何字段类型和一个栅格字段类型。每种几何字段类型对应于 OpenGIS Simple Features 规范 [^1]。对于栅格数据，没有类似的标准。

### `GeometryField`

#### `class GeometryField`

几何字段的基类。

### `PointField`

#### `class PointField`

存储一个 [`Point`](/zh-hans/6.1/ref/contrib/gis/geos/#django.contrib.gis.geos.Point)。

### `LineStringField`

#### `class LineStringField`

存储一个 [`LineString`](/zh-hans/6.1/ref/contrib/gis/geos/#django.contrib.gis.geos.LineString)。

### `PolygonField`

#### `class PolygonField`

存储一个 [`Polygon`](/zh-hans/6.1/ref/contrib/gis/geos/#django.contrib.gis.geos.Polygon)。

### `MultiPointField`

#### `class MultiPointField`

存储一个 [`MultiPoint`](/zh-hans/6.1/ref/contrib/gis/geos/#django.contrib.gis.geos.MultiPoint)。

### `MultiLineStringField`

#### `class MultiLineStringField`

存储一个 [`MultiLineString`](/zh-hans/6.1/ref/contrib/gis/geos/#django.contrib.gis.geos.MultiLineString)。

### `MultiPolygonField`

#### `class MultiPolygonField`

存储一个 [`MultiPolygon`](/zh-hans/6.1/ref/contrib/gis/geos/#django.contrib.gis.geos.MultiPolygon)。

### `GeometryCollectionField`

#### `class GeometryCollectionField`

存储一个 [`GeometryCollection`](/zh-hans/6.1/ref/contrib/gis/geos/#django.contrib.gis.geos.GeometryCollection)。

### `RasterField`

#### `class RasterField`

存储一个 [`GDALRaster`](/zh-hans/6.1/ref/contrib/gis/gdal/#django.contrib.gis.gdal.GDALRaster)。

`RasterField` 目前仅在 PostGIS 后端实现。

## 空间字段选项

除了 Django 模型字段可用的常规 常见模型字段选项 外，空间字段还有以下附加选项。所有这些选项都是可选的。

### `srid`

#### `BaseSpatialField.srid`

将几何字段的 SRID [^2] （空间参考系统标识）设置为给定值。默认值为 4326（也称为 [WGS84](https://en.wikipedia.org/wiki/WGS84)，单位为经度和纬度的度数）。

#### 选择一个 SRID

Choosing an appropriate SRID for your model is an important decision that the
developer should consider carefully. The SRID is an integer specifier that
corresponds to the projection system that will be used to interpret the data in
the spatial database. [^3]  Projection systems give the context to the
coordinates that specify a location. Although the details of [geodesy](https://en.wikipedia.org/wiki/Geodesy) are
beyond the scope of this documentation, the general problem is that the earth
is spherical and representations of the earth (e.g., paper maps, web maps) are
not.

Most people are familiar with using latitude and longitude to reference a
location on the earth's surface. However, latitude and longitude are angles,
not distances. In other words, while the shortest path between two points on a
flat surface is a straight line, the shortest path between two points on a
curved surface (such as the earth) is an *arc* of a [great circle](https://en.wikipedia.org/wiki/Great_circle).
[^4]

Thus, additional computation is required to obtain distances in planar units
(e.g., kilometers and miles). Using a geographic coordinate system may
introduce complications for the developer later on. For example, SpatiaLite
does not have the capability to perform distance calculations between
geometries using geographic coordinate systems, e.g. constructing a query to
find all points within 5 miles of a county boundary stored as WGS84. [^5]

Portions of the earth's surface may projected onto a two-dimensional, or
Cartesian, plane. Projected coordinate systems are especially convenient for
region-specific applications, e.g., if you know that your database will only
cover geometries in [North Kansas](https://spatialreference.org/ref/epsg/2796/), then you may consider using projection
system specific to that region. Moreover, projected coordinate systems are
defined in Cartesian units (such as meters or feet), easing distance
calculations.

> **Note**
>
> 如果您希望在 PostGIS 中使用 WGS84 中的非点几何体执行任意距离查询，并且希望获得良好的性能，请启用 [`GeometryField.geography`](#django.contrib.gis.db.models.GeometryField.geography) 关键字，以便使用 [地理数据库类型](#geography-type)。

其他资源：

- [spatialreference.org](https://spatialreference.org/): A database of spatial reference systems.
- [The State Plane Coordinate System](https://web.archive.org/web/20080302095452/http://welcome.warnercnr.colostate.edu/class_info/nr502/lg3/datums_coordinates/spcs.html): A website covering the various
  projection systems used in the United States. Much of the U.S. spatial
  data encountered will be in one of these coordinate systems rather than
  in a geographic coordinate system such as WGS84.

### `spatial_index`

#### `BaseSpatialField.spatial_index`

Defaults to `True`. Creates a spatial index for the given geometry
field.

> **Note**
>
> This is different from the `db_index` field option because spatial
> indexes are created in a different manner than regular database
> indexes. Specifically, spatial indexes are typically created using
> a variant of the R-Tree, while regular database indexes typically
> use B-Trees.

## 几何字段选项

几何字段还有其他可用的选项。以下所有选项都是可选的。

### `dim`

#### `GeometryField.dim`

This option may be used for customizing the coordinate dimension of the
geometry field. By default, it is set to 2, for representing two-dimensional
geometries. For spatial backends that support it, it may be set to 3 for
three-dimensional support.

> **Note**
>
> 目前，对三维的支持仅限于 PostGIS 和 SpatiaLite 后端。

### `geography`

#### `GeometryField.geography`

If set to `True`, this option will create a database column of
type geography, rather than geometry. Please refer to the
[geography type](#geography-type) section below for more
details.

> **Note**
>
> 地理支持仅限于 PostGIS，并且会强制将 SRID 设置为 4326。

### `max_geom_collections`

#### `GeometryField.max_geom_collections`

> **New in Django 5.2.17**

This option is forwarded to the [`form field`](/zh-hans/6.1/ref/contrib/gis/forms-api/#django.contrib.gis.forms.Field.max_geom_collections) generated for this model
field, bounding how many geometry collections may be contained in submitted
WKB/WKT inputs before raising [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError). Since spatial field
assignments are lazy, it is also checked when values are accessed, e.g. when
saving an instance, but not when read from a database. It defaults to `198`.

#### 地理类型

The geography type provides native support for spatial features represented
with geographic coordinates (e.g., WGS84 longitude/latitude). [^6]
Unlike the plane used by a geometry type, the geography type uses a spherical
representation of its data. Distance and measurement operations
performed on a geography column automatically employ great circle arc
calculations and return linear units. In other words, when `ST_Distance`
is called on two geographies, a value in meters is returned (as opposed
to degrees if called on a geometry column in WGS84).

由于地理计算涉及更多的数学运算，因此地理类型仅支持 PostGIS 空间查询的子集。实际上，这意味着除了 [距离查询](/zh-hans/6.1/ref/contrib/gis/geoquerysets/#distance-lookups) 之外，地理列仅支持以下其他 [空间查询](/zh-hans/6.1/ref/contrib/gis/geoquerysets/#spatial-lookups)：

- [`bboverlaps`](/zh-hans/6.1/ref/contrib/gis/geoquerysets/#std-fieldlookup-bboverlaps)
- [`coveredby`](/zh-hans/6.1/ref/contrib/gis/geoquerysets/#std-fieldlookup-coveredby)
- [`covers`](/zh-hans/6.1/ref/contrib/gis/geoquerysets/#std-fieldlookup-covers)
- [`intersects`](/zh-hans/6.1/ref/contrib/gis/geoquerysets/#std-fieldlookup-intersects)

如果您需要使用不支持地理类型作为输入的空间查询或聚合函数，您可以在查询中使用 [`Cast`](/zh-hans/6.1/ref/models/database-functions/#django.db.models.functions.Cast) 数据库函数将地理列转换为几何类型：

```
from django.contrib.gis.db.models import PointField
from django.db.models.functions import Cast

Zipcode.objects.annotate(geom=Cast("geography_field", PointField())).filter(
    geom__within=poly
)
```

For more information, the PostGIS documentation contains a helpful section on
determining [when to use geography data type over geometry data type](https://postgis.net/docs/using_postgis_dbmanagement.html#PostGIS_GeographyVSGeometry).

**脚注**

[^1]: OpenGIS Consortium, Inc., [Simple Feature Specification For SQL](https://www.ogc.org/standard/sfs/).

[^2]: *在第 2.3.8 章，第 39页 查看 id* （几何值和空间参考系统）。

[^3]: Typically, SRID integer corresponds to an EPSG ([European Petroleum Survey Group](https://epsg.org/)) identifier. However, it may also be associated with custom projections defined in spatial database's spatial reference systems table.

[^4]: Terry A. Slocum, Robert B. McMaster, Fritz C. Kessler 和 Hugh H. Howard，《主题制图和地理可视化》（Prentice Hall，第二版），第 7.1.3 节。

[^5]: 这个限制不适用于 PostGIS。

[^6]: 请参考 [PostGIS Geography Type](https://postgis.net/docs/using_postgis_dbmanagement.html#PostGIS_Geography) 文档以获取更多详细信息。