Ticket #12930: db-api.txt

File db-api.txt, 42.8 KB (added by adamfast, 14 years ago)

db-api.txt file to replace the one in place after applying the patch

Line 
1======================
2GeoDjango Database API
3======================
4
5.. currentmodule:: django.contrib.gis.db.models
6
7GeoDjango's lookup types may be used with any manager method like
8``filter()``, ``exclude()``, etc. However, the lookup types unique to
9GeoDjango are only available with geographic fields.
10Filters on 'normal' fields (e.g. ``CharField``) may be chained with those on
11geographic fields. Thus, geographic queries take the following form (assuming
12the ``Zipcode`` model used in the `GeoDjango Model API`_)::
13
14 >>> qs = Zipcode.objects.filter(<field>__<lookup_type>=<parameter>)
15 >>> qs = Zipcode.objects.exclude(...)
16
17For example::
18
19 >>> qs = Zipcode.objects.filter(poly__contains=pnt)
20
21In this case, ``poly`` is the geographic field, ``contains`` is the lookup type,
22and ``pnt`` is the parameter (which may be a ``GEOSGeometry`` object or a string
23of GeoJSON , WKT, or HEXEWKB).
24
25.. note::
26
27 GeoDjango constructs spatial SQL with the ``GeoQuerySet``, a
28 subclass of Django's ``QuerySet``. The ``GeoManager`` instance
29 attached to your model allows it to use ``GeoQuerySet``.
30
31.. _GeoDjango Model API: model-api.html
32
33Creating and Saving Geographic Models
34=====================================
35Here is an example of how to create a geometry object (assuming the ``Zipcode``
36model)::
37
38 >>> from zipcode.models import Zipcode
39 >>> z = Zipcode(code=77096, poly='POLYGON(( 10 10, 10 20, 20 20, 20 15, 10 10))')
40 >>> z.save()
41
42`GEOS geometry objects`_ may also be used to save geometric models::
43
44 >>> from django.contrib.gis.geos import GEOSGeometry
45 >>> z = Zipcode(code=77096, poly=GEOSGeometry('POLYGON(( 10 10, 10 20, 20 20, 20 15, 10 10))'))
46 >>> z.save()
47
48Moreover, if the ``GEOSGeometry`` is in a different coordinate system (has a
49different SRID value) than that of the field, then it will be implicitly
50transformed into the SRID of the model's field, using the spatial database's
51transform procedure::
52
53 >>> poly_3084 = GEOSGeometry('POLYGON(( 10 10, 10 20, 20 20, 20 15, 10 10))', srid=3084) # SRID 3084 is 'NAD83(HARN) / Texas Centric Lambert Conformal'
54 >>> z = Zipcode(code=78212, poly=poly_3084)
55 >>> z.save()
56 >>> from django.db import connection
57 >>> print connection.queries[-1]['sql'] # printing the last SQL statement executed (requires DEBUG=True)
58 INSERT INTO "geoapp_zipcode" ("code", "poly") VALUES (78212, ST_Transform(ST_GeomFromWKB('\\001 ... ', 3084), 4326))
59
60Thus, geometry parameters may be passed in using the ``GEOSGeometry`` object, WKT
61(Well Known Text [#]_), HEXEWKB (PostGIS specific -- a WKB geometry in
62hexadecimal [#]_), and GeoJSON [#]_ (requires GDAL). Essentially, if the input is not a
63``GEOSGeometry`` object, the geometry field will attempt to create a ``GEOSGeometry``
64instance from the input.
65
66Below are some examples of GEOS Geometry objects, WKT, and HEXEWKB, and
67GeoJSON:
68
69* GEOS Geometry::
70
71 >>> from django.contrib.gis.geos import *
72 >>> pnt = Point(5, 23)
73 >>> ls = LineString((0, 0), (5, 23))
74 >>> poly = GEOSGeometry('POLYGON (( 10 10, 10 20, 20 20, 20 15, 10 10))')
75
76* WKT Polygon: ``'POLYGON(( 10 10, 10 20, 20 20, 20 15, 10 10))'``
77* HEXEWKB Polygon : ``'0103000000010000000 ... 00000000000002440'``
78* GeoJSON Point: ``{ "type": "Point", "coordinates": [100.0, 0.0] }``
79
80.. _GEOS geometry objects: geos.html
81
82Spatial Lookup Types
83====================
84
85PostGIS
86-------
87
88Spatial Operators
89^^^^^^^^^^^^^^^^^
90
91The following lookup types correspond to PostGIS spatial operators. [#]_
92
93 :lookup:`bbcontains`
94 Tests if the geometry field's bounding box completely contains the lookup
95 geometry's bounding box.
96
97 Example::
98
99 Zipcode.objects.filter(poly__bbcontains=geom)
100
101 PostGIS equivalent::
102
103 SELECT ... WHERE poly ~ geom
104
105 :lookup:`bboverlaps`
106 Tests if the geometry field's bounding box overlaps the lookup geometry's
107 bounding box.
108
109 Example::
110
111 Zipcode.objects.filter(poly__bboverlaps=geom)
112
113 PostGIS equivalent::
114
115 SELECT ... WHERE poly && geom
116
117 :lookup:`contained`
118 Tests if the geometry field's bounding box is completely contained by the
119 lookup geometry's bounding box.
120
121 Example::
122
123 Zipcode.objects.filter(poly__contained=geom)
124
125 PostGIS equivalent::
126
127 SELECT ... WHERE poly @ geom
128
129 :lookup:`exact` or :lookup:`same_as`
130 Tests actual geometric equality of the geometry field against the the given
131 lookup geometry, vertex-by-vertex.
132
133 The following examples are equivalent::
134
135 Zipcode.objects.filter(poly__exact=geom)
136 Zipcode.objects.filter(poly=geom)
137 Zipcode.objects.filter(poly__same_as=geom)
138
139 PostGIS equivalent::
140
141 SELECT ... WHERE poly ~= geom
142
143 :lookup:`left`
144 Tests if the geometry field's bounding box is strictly to the left of the
145 lookup geometry's bounding box.
146
147 Example::
148
149 Zipcode.objects.filter(poly__left=geom)
150
151 PostGIS equivalent::
152
153 SELECT ... WHERE poly << geom
154
155 :lookup:`right`
156 Tests if the geometry field's bounding box is strictly to the right of the
157 lookup geometry's bounding box.
158
159 Example::
160
161 Zipcode.objects.filter(poly__right=geom)
162
163 PostGIS equivalent::
164
165 SELECT ... WHERE poly >> geom
166
167 lookup:`overlaps_left`
168 Tests if the geometry field's bounding box overlaps or is to the left of the lookup
169 geometry's bounding box.
170
171 Example::
172
173 Zipcode.objects.filter(poly__overlaps_left=geom)
174
175 PostGIS equivalent::
176
177 SELECT ... WHERE poly &< geom
178
179 :lookup:`overlaps_right`
180 Tests if the geometry field's bounding box overlaps or is to the right of the lookup
181 geometry's bounding box.
182
183 Example::
184
185 Zipcode.objects.filter(poly__overlaps_right=geom)
186
187 PostGIS equivalent::
188
189 SELECT ... WHERE poly &> geom
190
191 :lookup:`overlaps_above`
192 Tests if the geometry field's bounding box overlaps or is above the lookup
193 geometry's bounding box.
194
195 Example::
196
197 Zipcode.objects.filter(poly__overlaps_above=geom)
198
199 PostGIS equivalent::
200
201 SELECT ... WHERE poly |&> geom
202
203 :lookup:`overlaps_below`
204 Tests if the geometry field's bounding box overlaps or is below the lookup
205 geometry's bounding box.
206
207 Example::
208
209 Zipcode.objects.filter(poly__overlaps_below=geom)
210
211 PostGIS equivalent::
212
213 SELECT ... WHERE poly &<| geom
214
215 :lookup:`strictly_above`
216 Tests if the geometry field's bounding box is strictly above the lookup
217 geometry's bounding box.
218
219 Example::
220
221 Zipcode.objects.filter(poly__strictly_above=geom)
222
223 PostGIS equivalent::
224
225 SELECT ... WHERE poly |>> geom
226
227 :lookup:`strictly_below`
228 Tests if the geometry field's bounding box is strictly below the lookup
229 geometry's bounding box.
230
231 Example::
232
233 Zipcode.objects.filter(poly__strictly_below=geom)
234
235 PostGIS equivalent::
236
237 SELECT ... WHERE poly <<| geom
238
239Geometry Relationship Functions
240^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
241
242The following lookup types correspond to PostGIS geometry relationship
243functions. [#]_ Please note that when using PostGIS 1.3.1 and above, index
244support is automatically "inlined" -- in other words, the bounding box
245equivalent is automatically evaluated prior to calling these, more
246computationally expensive, functions.
247
248 :lookup:`contains`
249 Tests if the geometry field spatially contains the lookup geometry.
250
251 Example::
252
253 Zipcode.objects.filter(poly__contains=geom)
254
255 PostGIS equivalent::
256
257 SELECT ... WHERE ST_Contains(poly, geom)
258
259 :lookup:`coveredby`
260 Tests if no point in the geometry field is outside the lookup geometry. [#]_
261 Only available in PostGIS 1.3.1 and above.
262
263 Example::
264
265 Zipcode.objects.filter(poly__coveredby=geom)
266
267 PostGIS equivalent::
268
269 SELECT ... WHERE ST_CoveredBy(poly, geom)
270
271 :lookup:`covers`
272 Tests if no point in the lookup geometry is outside the geometry field. [#]_
273 Only available in PostGIS 1.3.1 and above.
274
275 Example::
276
277 Zipcode.objects.filter(poly__covers=geom)
278
279 PostGIS equivalent::
280
281 SELECT ... WHERE ST_Covers(poly, geom)
282
283 :lookup:`crosses`
284 Tests if the geometry field spatially crosses the lookup geometry.
285
286 Example::
287
288 Zipcode.objects.filter(poly__crosses=geom)
289
290 PostGIS equivalent::
291
292 SELECT ... WHERE ST_Crosses(poly, geom)
293
294 :lookup:`disjoint`
295 Tests if the geometry field is spatially disjoint from the lookup geometry.
296
297 Example::
298
299 Zipcode.objects.filter(poly__disjoint=geom)
300
301 PostGIS equivalent::
302
303 SELECT ... WHERE ST_Disjoint(poly, geom)
304
305.. _dwithin_postgis:
306
307 :lookup:`dwithin`
308 Tests if the geometry field is within the specified distance of the lookup
309 geometry; uses indexes if available. The lookup parameter is a two-element
310 tuple: ``(geom, distance)``, where ``distance`` is a ``Distance`` object or a
311 numeric value in units. Only available in PostGIS versions 1.3.1 and above.
312
313 .. admonition:: Distance Parameters and Geographic Coordinate Systems
314
315 The ``dwithin`` lookup is meant for projected coordinate systems
316 because PostGIS uses ``ST_Distance``, which calculates the
317 Cartesian distance between geometries. In other words,
318 this will not return accurate results for geographic coordinate
319 systems such as WGS84. Thus, an exception will be raised if a
320 ``Distance`` object is used on a geometry field in a geographic
321 coordinate system.
322
323 However, a numeric value is allowed for geometry fields in geographic
324 coordinate systems. This advanced usage allows users to limit
325 querysets by distance more efficiently using units of degrees.
326
327 Example::
328
329 # If Zipcode uses a projected coordinate system, this is allowed.
330 Zipcode.objects.filter(poly__dwithin=(geom, D(mi=5)))
331
332 # If Zipcode uses a geographic coordinate system, then the
333 # distance unit must be a numeric value in units of degrees.
334 Zipcode.objects.filter(poly__dwithin=(geom, 0.5))
335
336 PostGIS equivalent::
337
338 SELECT ... WHERE ST_DWithin(poly, geom, <units value>)
339
340 :lookup:`equals`
341 Tests if the geometry field is spatially equal to the lookup geometry.
342
343 Example::
344
345 Zipcode.objects.filter(poly__equals=geom)
346
347 PostGIS equivalent::
348
349 SELECT ... WHERE ST_Equals(poly, geom)
350
351 :lookup:`intersects`
352 Tests if the geometry field spatially intersects the lookup geometry.
353
354 Example::
355
356 Zipcode.objects.filter(poly__intersects=geom)
357
358 PostGIS equivalent::
359
360 SELECT ... WHERE ST_Intersects(poly, geom)
361
362 :lookup:`overlaps`
363 Tests if the geometry field spatially overlaps the lookup geometry.
364
365 Example::
366
367 Zipcode.objects.filter(poly__overlaps=geom)
368
369 PostGIS equivalent::
370
371 SELECT ... WHERE ST_Overlaps(poly, geom)
372
373 :lookup:`relate`
374 Tests if the geometry field is spatially related to the the lookup geometry by
375 the values given in the intersection pattern matrix. The intersection pattern
376 matrix is a string comprising nine characters, which define intersections between
377 the interior, boundary, and exterior of the geometry field and the lookup geometry.
378 The intersection pattern matrix may only use the following characters:
379 ``1``, ``2``, ``T``, ``F``, or ``*``. This lookup type allows users to "fine tune"
380 a specific geometric relationship consistent with the DE-9IM model. [#]_
381
382 Example::
383
384 # A tuple lookup parameter is used to specify the geometry and
385 # the intersection pattern (the pattern here is for 'contains').
386 Zipcode.objects.filter(poly__relate(geom, 'T*T***FF*'))
387
388 PostGIS equivalent::
389
390 SELECT ... WHERE ST_Relate(poly, geom, 'T*T***FF*')
391
392 :lookup:`touches`
393 Tests if the geometry field spatially touches the lookup geometry.
394
395 Example::
396
397 Zipcode.objects.filter(poly__touches=geom)
398
399 PostGIS equivalent::
400
401 SELECT ... WHERE ST_Touches(poly, geom)
402
403 :lookup:`within`
404 Tests if the geometry field is spatially within the lookup geometry.
405
406 Example::
407
408 Zipcode.objects.filter(poly__within=geom)
409
410 PostGIS equivalent::
411
412 SELECT ... WHERE ST_Within(poly, geom)
413
414
415Oracle
416------
417For more information, see Oracle's `Spatial Operators`__ documentation. [#]_
418
419__ http://download.oracle.com/docs/html/B14255_01/sdo_operat.htm
420
421 :lookup:`contains`
422 Tests if the geometry field spatially contains the lookup geometry.
423
424 Example::
425
426 Zipcode.objects.filter(poly__contains=geom)
427
428 Oracle equivalent::
429
430 SELECT ... WHERE SDO_CONTAINS(poly, geom)
431
432 :lookup:`covers`
433 Tests if no point in the lookup geometry is outside the geometry field.
434
435 Oracle equivalent::
436
437 SELECT ... WHERE SDO_COVERS(poly, geom)
438
439 :lookup:`coveredby`
440 Tests if no point in the geometry field is outside the lookup geometry.
441
442 Oracle equivalent::
443
444 SELECT ... WHERE SDO_COVEREDBY(poly, geom)
445
446 :lookup:`disjoint`
447 Tests if the geometry field is spatially disjoint from the lookup geometry.
448
449 Oracle equivalent::
450
451 SELECT ... WHERE SDO_GEOM.RELATE(poly, 'DISJOINT', geom, 0.05)
452
453 :lookup:`dwithin`
454 Tests if the geometry field is within the specified distance of the lookup
455 geometry; uses indexes if available. The lookup parameter is a two-element
456 tuple: ``(geom, distance)``, where ``distance`` is a ``Distance`` object or a
457 numeric value in units.
458
459 Oracle equivalent::
460
461 SELECT ... WHERE SDO_WITHIN_DISTANCE(poly, geom, 'distance=distance')
462
463 :lookup:`equals`, :lookup:`exact`, :lookup:`same_as`
464 Tests if the geometry field is spatially equal to the lookup geometry.
465 The following examples are equivalent on Oracle::
466
467 Zipcode.objects.filter(poly=geom)
468 Zipcode.objects.filter(poly__exact=geom)
469 Zipcode.objects.filter(poly__equals=geom)
470 Zipcode.objects.filter(poly__same_as=geom)
471
472 Oracle equivalent::
473
474 SELECT ... WHERE SDO_EQUALS(poly, geom)
475
476 :lookup:`intersects`
477 Tests if the geometry field spatially intersects the lookup geometry.
478
479 Oracle equivalent::
480
481 SELECT ... WHERE SDO_OVERLAPBDYINTERSECT(poly, geom)
482
483 :lookup:`overlaps`
484 Tests if the geometry field spatially overlaps the lookup geometry.
485
486 Oracle equivalent::
487
488 SELECT ... WHERE SDO_OVERLAPS(poly, geom)
489
490 :lookup:`relate`
491 Tests if the geometry field is spatially related to the the lookup geometry by
492 the given mask component. This lookup requires a tuple parameter,
493 ``(geom, mask)``, where ``mask`` is at least one of the nine-intersection
494 patterns: ``TOUCH``, ``OVERLAPBDYDISJOINT``, ``OVERLAPBDYINTERSECT``,
495 ``EQUAL``, ``INSIDE``, ``COVEREDBY``, ``CONTAINS``, ``COVERS``, ``ANYINTERACT``,
496 and ``ON``. Multiple masks may be combined with the logical Boolean operator
497 OR, for example, ``'inside+touch'``. [#]_ The mask relation strings are
498 case-insensitive.
499
500 Example::
501
502 # A tuple lookup parameter is used to specify the geometry and
503 # the mask component.
504 Zipcode.objects.filter(poly__relate(geom, 'anyinteract'))
505
506 Oracle equivalent::
507
508 SELECT ... WHERE SDO_RELATE(poly, geom, 'anyinteract')
509
510 :lookup:`touches`
511 Tests if the geometry field spatially touches the lookup geometry.
512
513 Oracle equivalent::
514
515 SELECT ... WHERE SDO_TOUCH(poly, geom)
516
517 :lookup:`within`
518 Tests if the geometry field is spatially within (inside) the lookup
519 geometry.
520
521 Oracle equivalent::
522
523 SELECT ... WHERE SDO_INSIDE(poly, geom)
524
525MySQL
526-----
527For more information, see `Relations on Geometry Minimal Bounding Rectangles (MBRs)`__. [#]_
528
529__ http://dev.mysql.com/doc/refman/5.0/en/relations-on-geometry-mbr.html
530
531 :lookup:`bbcontains`, :lookup:`contains`
532 * MySQL equivalent ``MBRContains(g1, g2)``
533
534 :lookup:`contained`, :lookup:`within`
535 * MySQL equivalent ``MBRWithin(g1, g2)``
536
537 :lookup:`disjoint`
538 * MySQL equivalent ``MBRDisjoint(g1, g2)``
539
540 :lookup:`equals`, :lookup:`exact`, :lookup:`same_as`
541 * MySQL equivalent ``MBREqual(g1, g2)``
542
543 :lookup:`intersects`
544 * MySQL equivalent ``MBRIntersects(g1, g2)``
545
546 :lookup:`overlaps`
547 * MySQL equivalent ``MBROverlaps(g1, g2)``
548
549 :lookup:`touches`
550 * MySQL equivalent ``MBRTouches(g1, g2)``
551
552SpatiaLite
553----------
554
555For more information consult the `SpatiaLite SQL functions reference list`__.
556
557__ http://www.gaia-gis.it/spatialite/spatialite-sql-2.3.1.html
558
559 :lookup:`bbcontains`
560 * SpatiaLite equivalient ``MbrContains(g1, g2)``
561
562 :lookup:`bboverlaps`
563 * SpatiaLite equivalent ``MbrOverlaps(g1, g2)``
564
565 :lookup:`contained`
566 * SpatiaLite equivalent ``MbrWithin(g1, g2)``
567
568 :lookup:`contains`
569 * SpatiaLite equivalent ``Contains(g1, g2)``
570
571 :lookup:`crosses`
572 * SpatiaLite equivalent ``Crosses(g1, g2)``
573
574 :lookup:`disjoint`
575 * SpatiaLite equivalent ``Disjoint(g1, g2)``
576
577 :lookup:`equals`, :lookup:`exact`, :lookup:`same_as`
578 * SpatiaLite equivalent ``Equals(g1, g2)``
579
580 :lookup:`intersects`
581 * SpatiaLite equivalent ``Intersects(g1, g2)``
582
583 :lookup:`overlaps`
584 * SpatiaLite equivalent ``Overlaps(g1, g2)``
585
586 :lookup:`relate`
587 * SpatiaLite equivalent ``Relate(geom, pattern)``
588
589 :lookup:`touches`
590 * SpatiaLite equivalent ``Touches(g1, g2)``
591
592 :lookup:`within`
593 * SpatiaLite equivalent ``Within(g1, g2)``
594
595
596Distance Queries
597================
598
599Introduction
600------------
601Distance calculations with spatial data is tricky because, unfortunately,
602the Earth is not flat. Some distance queries with fields in a geographic
603coordinate system may have to be expressed differently because of
604limitations in PostGIS. Please see the `Selecting an SRID`_ section in the
605model API documentation for more details.
606
607.. _Selecting an SRID: model-api.html#selecting-an-srid
608
609Distance Lookups
610----------------
611*Availability*: PostGIS, Oracle, SpatiaLite
612
613Distance lookups take a tuple parameter comprising:
614
615#. A geometry to base calculations from; and
616#. A number or ``Distance`` object containing the distance.
617
618If a ``Distance`` [#]_ object is used, it may be expressed in
619any units (the SQL generated will use units converted to those of the field);
620otherwise, numeric parameters will be assumed to be in the units of the field.
621
622.. note::
623
624 For PostGIS users, the routine ``ST_distance_sphere``
625 is used by default for calculating distances on geographic coordinate systems
626 -- which may only be called with point geometries [#]_. Thus,
627 geographic distance lookups on PostGIS are only allowed on ``PointField``
628 model fields using points for the geographic parameter.
629
630The following distance lookups are available:
631
632* :lookup:`distance_lt`
633* :lookup:`distance_lte`
634* :lookup:`distance_gt`
635* :lookup:`distance_gte`
636* :lookup:`dwithin`
637
638In addition, there's the :ref:`distance` ``GeoQuerySet`` method.
639
640For example, let's say we have a ``SouthTexasCity`` model (from the
641`GeoDjango distance tests`__ ) on a *projected* coordinate system valid for cities
642in southern Texas::
643
644 from django.contrib.gis.db import models
645
646 class SouthTexasCity(models.Model):
647 name = models.CharField(max_length=30)
648 # A projected coordinate system (only valid for South Texas!)
649 # is used, units are in meters.
650 point = models.PointField(srid=32140)
651 objects = models.GeoManager()
652
653Then distance queries may be performed as follows::
654
655 >>> from django.contrib.gis.geos import *
656 >>> from django.contrib.gis.measure import D # ``D`` is a shortcut for ``Distance``
657 >>> from geoapp import SouthTexasCity
658 # Distances will be calculated from this point, which does not have to be projected.
659 >>> pnt = fromstr('POINT(-96.876369 29.905320)', srid=4326)
660 # If numeric parameter, units of field (meters in this case) are assumed.
661 >>> qs = SouthTexasCity.objects.filter(point__distance_lte=(pnt, 7000))
662 # Find all Cities within 7 km, > 20 miles away, and > 100 chains away (an obscure unit)
663 >>> qs = SouthTexasCity.objects.filter(point__distance_lte=(pnt, D(km=7)))
664 >>> qs = SouthTexasCity.objects.filter(point__distance_gte=(pnt, D(mi=20)))
665 >>> qs = SouthTexasCity.objects.filter(point__distance_gte=(pnt, D(chain=100)))
666
667__ http://code.djangoproject.com/browser/django/trunk/django/contrib/gis/tests/distapp/models.py
668
669.. _geoqs_methods:
670
671``GeoQuerySet`` Methods
672=======================
673
674``GeoQuerySet`` methods perform a spatial operation on each geographic
675field in the queryset and store its output in a new attribute on the model
676(which is generally the name of the ``GeoQuerySet`` method).
677
678There are also aggregate ``GeoQuerySet`` methods which return a single value
679instead of a queryset. This section will describe the API and availability
680of every ``GeoQuerySet`` method available in GeoDjango.
681
682With a few exceptions, the following keyword arguments may be used with all
683``GeoQuerySet`` methods:
684
685===================== =====================================================
686Keyword Argument Description
687===================== =====================================================
688``field_name`` By default, ``GeoQuerySet`` methods use the first
689 geographic field encountered in the model. This
690 keyword should be used to specify another
691 geographic field (e.g., ``field_name='point2'``)
692 when there are multiple geographic fields in a model.
693
694 On PostGIS, the ``field_name`` keyword may also be
695 used on geometry fields in models that are related
696 via a ``ForeignKey`` relation (e.g.,
697 ``field_name='related__point'``).
698
699``model_att`` By default, ``GeoQuerySet`` methods typically attach
700 their output in an attribute with the same name as
701 the ``GeoQuerySet`` method. Setting this keyword
702 with the desired attribute name will override this
703 default behavior. For example,
704 ``qs = Zipcode.objects.centroid(model_att='c')`` will
705 attach the centroid of the ``Zipcode`` geometry field
706 in a ``c`` attribute on every model rather than in a
707 ``centroid`` attribute.
708
709 This keyword is required if
710 a method name clashes with an existing
711 ``GeoQuerySet`` method -- if you wanted to use the
712 ``area()`` method on model with a ``PolygonField``
713 named ``area``, for example.
714===================== =====================================================
715
716Aggregate Objects
717-----------------
718.. versionadded:: 1.1
719
720Example::
721
722 >>> from django.contrib.gis.db.models import Extent, Union
723 >>> WorldBorders.objects.aggregate(Extent('mpoly'), Union('mpoly'))
724
725.. method:: Collect
726
727Returns the same as the :ref:`collect` aggregate method.
728
729.. method:: Extent
730
731Returns the same as the :ref:`extent` aggregate method.
732
733.. method:: Extent3D
734
735.. versionadded:: 1.2
736
737Returns the same as the :ref:`extent3d` aggregate method.
738
739.. method:: MakeLine
740
741Returns the same as the :ref:`makeline` aggregate method.
742
743.. method:: Union
744
745Returns the same as the :ref:`unionagg` aggregate method.
746
747Aggregate Methods
748-----------------
749
750.. _collect:
751
752.. method:: collect()
753
754.. versionadded:: 1.1
755
756*Availability*: PostGIS
757
758Returns a ``GEOMETRYCOLLECTION`` or a ``MULTI`` geometry object from the geometry
759column. This is analagous to a simplified version of the :ref:`unionagg` routine,
760except it can be several orders of magnitude faster than peforming a union because
761it simply rolls up geometries into a collection or multi object, not caring about
762dissolving boundaries.
763
764.. _extent:
765
766.. method:: extent()
767
768*Availability*: PostGIS, Oracle
769
770Returns the extent of the ``GeoQuerySet`` as a four-tuple, comprising the
771lower left coordinate and the upper right coordinate.
772
773Example::
774
775 >>> qs = City.objects.filter(name__in=('Houston', 'Dallas'))
776 >>> print qs.extent()
777 (-96.8016128540039, 29.7633724212646, -95.3631439208984, 32.782058715820)
778
779
780.. _extent3d:
781
782.. method:: extent3d()
783
784.. versionadded:: 1.2
785
786*Availability*: PostGIS
787
788Returns the 3D extent of the ``GeoQuerySet`` as a six-tuple, comprising
789the lower left coordinate and upper right coordinate.
790
791Example::
792
793 >>> qs = City.objects.filter(name__in=('Houston', 'Dallas'))
794 >>> print qs.extent3d()
795 (-96.8016128540039, 29.7633724212646, 0, -95.3631439208984, 32.782058715820, 0)
796
797.. _makeline:
798
799.. method:: make_line()
800
801*Availability*: PostGIS
802
803Returns a ``LineString`` constructed from the point field geometries in the
804``GeoQuerySet``. Currently, ordering the queryset has no effect.
805
806Example::
807
808 >>> print City.objects.filter(name__in=('Houston', 'Dallas')).make_line()
809 LINESTRING (-95.3631510000000020 29.7633739999999989, -96.8016109999999941 32.7820570000000018)
810
811.. _unionagg:
812
813.. function:: unionagg()
814
815*Availability*: PostGIS, Oracle, SpatiaLite
816
817This method returns a ``GEOSGeometry`` object comprising the union of every
818geometry in the queryset. Please note that use of `unionagg` is processor intensive
819and may take a significant amount of time on large querysets.
820
821Example::
822
823 >>> u = Zipcode.objects.unionagg() # This may take a long time.
824 >>> u = Zipcode.objects.filter(poly__within=bbox).unionagg() # A more sensible approach.
825
826===================== =====================================================
827Keyword Argument Description
828===================== =====================================================
829``tolerance`` This keyword is for Oracle only. It is for the
830 tolerance value used by the ``SDOAGGRTYPE``
831 procedure; the `Oracle documentation`__ has more
832 details.
833===================== =====================================================
834
835__ http://download.oracle.com/docs/html/B14255_01/sdo_intro.htm#sthref150
836
837Measurement
838-----------
839*Availability*: PostGIS, Oracle, SpatiaLite
840
841.. _area:
842
843.. function:: area()
844
845Returns the area of the geographic field in an ``area`` attribute on
846each element of this GeoQuerySet.
847
848.. _distance:
849
850.. function:: distance(geom)
851
852This method takes a geometry as a parameter, and attaches a ``distance``
853attribute to every model in the returned queryset that contains the
854distance (as a ``Distance`` object) to the given geometry.
855
856In the following example (taken from the `GeoDjango distance tests`__),
857the distance from the `Tasmanian`__ city of Hobart to every other
858``PointField`` in the ``AustraliaCity`` queryset is calculated::
859
860 >>> pnt = AustraliaCity.objects.get(name='Hobart').point
861 >>> for city in AustraliaCity.objects.distance(pnt): print city.name, city.distance
862 Wollongong 990071.220408 m
863 Shellharbour 972804.613941 m
864 Thirroul 1002334.36351 m
865 Mittagong 975691.632637 m
866 Batemans Bay 834342.185561 m
867 Canberra 598140.268959 m
868 Melbourne 575337.765042 m
869 Sydney 1056978.87363 m
870 Hobart 0.0 m
871 Adelaide 1162031.83522 m
872 Hillsdale 1049200.46122 m
873
874.. note::
875
876 Because the ``distance`` attribute is a ``Distance`` object, you can
877 easily express the value in the units of your choice. For example,
878 ``city.distance.mi`` is the distance value in miles and
879 ``city.distance.km`` is the distance value in kilometers. See the
880 `distance documentation`_ for usage details and the list of
881 `supported units`_.
882
883.. _distance documentation: measure.html#the-distance-and-area-objects
884.. _supported units: measure.html#supported-units
885
886__ http://en.wikipedia.org/wiki/Tasmania
887__ http://code.djangoproject.com/browser/django/trunk/django/contrib/gis/tests/distapp/models.py
888
889.. function:: length()
890
891Returns the length of the geometry field in a ``length`` attribute
892(a ``Distance`` object) on each model in the queryset.
893
894.. function:: perimiter()
895
896Returns the perimeter of the geometry field in a ``perimeter`` attribute
897(a ``Distance`` object) on each model in the queryset.
898
899Geometry Methods
900----------------
901
902With the exception of ``transform``, all of the following attach geometry objects
903to each element of the ``GeoQuerySet`` that is the result of the method.
904
905.. function:: centroid()
906
907*Availability*: PostGIS, Oracle, SpatiaLite
908
909Returns the ``centroid`` value for the geographic field in a ``centroid``
910attribute on each element of the ``GeoQuerySet``.
911
912.. function:: envelope()
913
914*Availability*: PostGIS, SpatiaLite
915
916Returns a geometry representing the bounding box of the geometry field in
917an ``envelope`` attribute on each element of the ``GeoQuerySet``.
918
919.. function: point_on_surface()
920
921*Availability*: PostGIS, Oracle, SpatiaLite
922
923Returns a Point geometry guaranteed to lie on the surface of the
924Geometry field in a `point_on_surface` attribute on each element
925of this GeoQuerySet; otherwise sets with None.
926
927.. function:: scale(x, y, z=0.0)
928
929*Availability*: PostGIS, SpatiaLite
930
931.. function:: snap_to_grid(*args)
932
933.. versionadded:: 1.1
934
935Snap all points of the input geometry to the grid. How the
936geometry is snapped to the grid depends on how many numeric
937(either float, integer, or long) arguments are given.
938
939=================== =====================================================
940Number of Arguments Description
941=================== =====================================================
9421 A single size to snap bot the X and Y grids to.
9432 X and Y sizes to snap the grid to.
9444 X, Y sizes and the corresponding X, Y origins.
945=================== =====================================================
946
947.. function:: translate(x, y, z=0.0)
948
949*Availability*: PostGIS, SpatiaLite
950
951Translates the geometry to a new location using the given numeric
952parameters as offsets.
953
954.. function:: transform(srid)
955
956*Availability*: PostGIS, Oracle
957
958The ``transform`` method transforms the geometries in a model to the spatial
959reference system specified by the ``srid`` parameter. If no ``srid`` is given,
960then 4326 (WGS84) is used by default.
961
962.. note ::
963
964 What spatial reference system an integer SRID corresponds to may depend on
965 the spatial database used. In other words, the SRID numbers used for Oracle
966 are not necessarily the same as those used by PostGIS.
967
968Example::
969
970 >>> qs = Zipcode.objects.all().transform() # Transforms to WGS84
971 >>> qs = Zipcode.objects.all().transform(32140) # Transforming to "NAD83 / Texas South Central"
972 >>> print qs[0].poly.srid
973 32140
974 >>> print qs[0].poly
975 POLYGON ((234055.1698884720099159 4937796.9232223574072123 ...
976
977Geometry Operations
978-------------------
979*Availability*: PostGIS, Oracle, SpatiaLite
980
981The following methods all take a geometry as a parameter and attach a geometry
982to each element of the ``GeoQuerySet`` that is the result of the operation.
983
984.. function:: difference(geom)
985
986Returns the spatial difference of the geographic field with the given
987geometry in a ``difference`` attribute on each element of the
988``GeoQuerySet``.
989
990.. function:: intersection(geom)
991
992Returns the spatial intersection of the geographic field with the
993given geometry in an ``intersection`` attribute on each element of the
994``GeoQuerySet``.
995
996.. function:: sym_difference(geom)
997
998Returns the symmetric difference of the geographic field with the
999given geometry in a ``sym_difference`` attribute on each element of the
1000``GeoQuerySet``.
1001
1002.. function:: union(geom)
1003
1004Returns the union of the geographic field with the given
1005geometry in an ``union`` attribute on each element of the
1006``GeoQuerySet``.
1007
1008Output
1009------
1010
1011The following ``GeoQuerySet`` methods will return an attribute that has the value
1012of the geometry field in each model converted to the requested output format.
1013
1014.. function:: geojson()
1015
1016.. versionadded:: 1.1
1017
1018*Availability*: PostGIS
1019
1020Attaches a ``geojson`` attribute to every model in the queryset that contains the
1021`GeoJSON`__ representation of the geometry.
1022
1023===================== =====================================================
1024Keyword Argument Description
1025===================== =====================================================
1026``precision`` It may be used to specify the number of significant
1027 digits for the coordinates in the GeoJSON
1028 representation -- the default value is 8.
1029
1030``crs`` Set this to ``True`` if you want the coordinate
1031 reference system to be included in the returned
1032 GeoJSON.
1033
1034``bbox`` Set this to ``True`` if you want the bounding box
1035 to be included in the returned GeoJSON.
1036===================== =====================================================
1037
1038__ http://geojson.org/
1039
1040.. function:: gml()
1041
1042*Availability*: PostGIS, Oracle
1043
1044Attaches a ``gml`` attribute to every model in the queryset that contains the
1045`Geographic Markup Language (GML)`__ representation of the geometry.
1046
1047Example::
1048
1049 >>> qs = Zipcode.objects.all().gml()
1050 >>> print qs[0].gml
1051 <gml:Polygon srsName="EPSG:4326"><gml:OuterBoundaryIs>-147.78711,70.245363 ... -147.78711,70.245363</gml:OuterBoundaryIs></gml:Polygon>
1052
1053===================== =====================================================
1054Keyword Argument Description
1055===================== =====================================================
1056``precision`` This keyword is for PostGIS only. It may be used
1057 to specify the number of significant digits for the
1058 coordinates in the GML representation -- the default
1059 value is 8.
1060
1061``version`` This keyword is for PostGIS only. It may be used to
1062 specify the GML version used, and may only be values
1063 of 2 or 3. The default value is 2.
1064===================== =====================================================
1065
1066__ http://en.wikipedia.org/wiki/Geography_Markup_Language
1067
1068.. function:: kml()
1069
1070*Availability*: PostGIS
1071
1072Attaches a ``kml`` attribute to every model in the queryset that contains the
1073`Keyhole Markup Language (KML)`__ representation of the geometry fields. It
1074should be noted that the contents of the KML are transformed to WGS84 if
1075necessary.
1076
1077Example::
1078
1079 >>> qs = Zipcode.objects.all().kml()
1080 >>> print qs[0].kml
1081 <Polygon><outerBoundaryIs><LinearRing><coordinates>-103.04135,36.217596,0 ... -103.04135,36.217596,0</coordinates></LinearRing></outerBoundaryIs></Polygon>
1082
1083===================== =====================================================
1084Keyword Argument Description
1085===================== =====================================================
1086``precision`` This keyword may be used to specify the number of
1087 significant digits for the coordinates in the KML
1088 representation -- the default value is 8.
1089===================== =====================================================
1090
1091__ http://code.google.com/apis/kml/documentation/
1092
1093.. function:: svg()
1094
1095*Availability*: PostGIS, SpatiaLite
1096
1097Attaches a ``svg`` attribute to every model in the queryset that contains
1098the `Scalable Vector Graphics (SVG)`__ path data of the geometry fields.
1099
1100===================== =====================================================
1101Keyword Argument Description
1102===================== =====================================================
1103``relative`` If set to ``True``, the path data will be implemented
1104 in terms of relative moves. Defaults to ``False``,
1105 meaning that absolute moves are used instead.
1106
1107``precision`` This keyword may be used to specify the number of
1108 significant digits for the coordinates in the SVG
1109 representation -- the default value is 8.
1110===================== =====================================================
1111
1112__ http://www.w3.org/Graphics/SVG/
1113
1114Miscellaneous
1115-------------
1116
1117.. function:: mem_size()
1118
1119*Availability*: PostGIS
1120
1121Returns the memory size (number of bytes) that the geometry field takes
1122in a ``mem_size`` attribute on each element of the ``GeoQuerySet``.
1123
1124.. function:: num_geom()
1125
1126*Availability*: PostGIS, Oracle, SpatiaLite
1127
1128Returns the number of geometries in a ``num_geom`` attribute on
1129each element of the ``GeoQuerySet`` if the geometry field is a
1130collection (e.g., a ``GEOMETRYCOLLECTION`` or ``MULTI*`` field);
1131otherwise sets with ``None``.
1132
1133.. function:: num_points()
1134
1135*Availability*: PostGIS, Oracle, SpatiaLite
1136
1137Returns the number of points in the first linestring in the
1138geometry field in a ``num_points`` attribute on each element of
1139the ``GeoQuerySet``; otherwise sets with ``None``.
1140
1141Compatibility Table
1142===================
1143
1144Spatial Lookup Types
1145--------------------
1146The following table provides a summary of what lookup types are available
1147on each spatial backend.
1148
1149=========================== ========= ======== ============ ==========
1150Lookup Type PostGIS Oracle MySQL [#]_ SpatiaLite
1151=========================== ========= ======== ============ ==========
1152``bbcontains`` X X X
1153``bboverlaps`` X X X
1154``contained`` X X X
1155``contains`` X X X X
1156``coveredby`` X X
1157``covers`` X X
1158``crosses`` X X
1159``disjoint`` X X X X
1160``distance_gt`` X X X
1161``distance_gte`` X X X
1162``distance_lt`` X X X
1163``distance_lte`` X X X
1164``dwithin`` X X
1165``equals`` X X X X
1166``exact`` X X X X
1167``intersects`` X X X X
1168``overlaps`` X X X X
1169``relate`` X X X
1170``same_as`` X X X X
1171``touches`` X X X X
1172``within`` X X X X
1173``left`` X
1174``right`` X
1175``overlaps_left`` X
1176``overlaps_right`` X
1177``overlaps_above`` X
1178``overlaps_below`` X
1179``strictly_above`` X
1180``strictly_below`` X
1181=========================== ========= ======== ============ ==========
1182
1183``GeoQuerySet`` Methods
1184-----------------------
1185The following table provides a summary of what ``GeoQuerySet`` methods
1186are available on each spatial backend. Please note that MySQL does not
1187support any of these methods, and is thus excluded from the table.
1188
1189=========================== ========= ======== ==========
1190Method PostGIS Oracle SpatiaLite
1191=========================== ========= ======== ==========
1192``area`` X X X
1193``centroid`` X X X
1194``collect`` X
1195``difference`` X X X
1196``distance`` X X X
1197``envelope`` X X
1198``extent`` X X
1199``extent3d`` X
1200``geojson`` X
1201``gml`` X X
1202``intersection`` X X X
1203``kml`` X
1204``length`` X X X
1205``make_line`` X
1206``mem_size`` X
1207``num_geom`` X X X
1208``num_points`` X X X
1209``perimeter`` X X
1210``point_on_surface`` X X X
1211``scale`` X X
1212``snap_to_grid`` X
1213``svg`` X X
1214``sym_difference`` X X X
1215``transform`` X X X
1216``translate`` X X
1217``union`` X X X
1218``unionagg`` X X X
1219=========================== ========= ======== ==========
1220
1221.. rubric:: Footnotes
1222.. [#] *See* Open Geospatial Consortium, Inc., `OpenGIS Simple Feature Specification For SQL <http://www.opengis.org/docs/99-049.pdf>`_, Document 99-049 (May 5, 1999), at Ch. 3.2.5, p. 3-11 (SQL Textual Representation of Geometry).
1223.. [#] *See* `PostGIS EWKB, EWKT and Canonical Forms <http://postgis.refractions.net/documentation/manual-1.3/ch04.html#id2571020>`_, PostGIS documentation at Ch. 4.1.2.
1224.. [#] *See* Howard Butler, Martin Daly, Allan Doyle, Tim Schaub, & Christopher Schmidt, `The GeoJSON Format Specification <http://geojson.org/geojson-spec.html>`_, Revision 1.0 (June 16, 2008).
1225.. [#] *See generally*, `Operators <http://postgis.refractions.net/documentation/manual-1.3/ch06.html#id2576880>`_, PostGIS Documentation at Ch. 6.2.2.
1226.. [#] *See generally*, `Geometry Relationship Functions <http://postgis.refractions.net/documentation/manual-1.3/ch06.html#id2574517>`_ PostGIS Documentation at Ch. 6.1.2.
1227.. [#] For an explanation of this routine, see `this entry <http://lin-ear-th-inking.blogspot.com/2007/06/subtleties-of-ogc-covers-spatial.html>`_ at the blog of Martin Davis (a PostGIS developer).
1228.. [#] *See id.*
1229.. [#] *See* `OpenGIS Simple Feature Specification For SQL <http://www.opengis.org/docs/99-049.pdf>`_, at Ch. 2.1.13.2, p. 2-13 (The Dimensionally Extended Nine-Intersection Model).
1230.. [#] Oracle Spatial User's Guide and Manual, at Ch. 11.
1231.. [#] *See id.* at `SDO_RELATE documentation <http://download.oracle.com/docs/cd/B19306_01/appdev.102/b14255/sdo_operat.htm#sthref845>`_.
1232.. [#] MySQL 5.0 Reference Manual, at Ch. 17.5.5.
1233.. [#] *See* the `distance documentation`_ for more information on the ``Distance`` object.
1234.. [#] *See* ``ST_distance_sphere`` in `Measurement Functions <http://postgis.refractions.net/documentation/manual-1.3/ch06.html#id2577138>`_, PostGIS documentation at Ch. 6.2.3.
1235.. [#] MySQL only supports bounding box operations (known as minimum bounding rectangles, or MBR, in MySQL). Thus, spatial lookups such as ``contains`` are really equivalent to ``bbcontains``.
Back to Top