Changeset 2741
- Timestamp:
- 04/23/06 18:22:42 (3 years ago)
- Files:
-
- django/branches/magic-removal/docs/db-api.txt (modified) (33 diffs)
Legend:
- Unmodified
- Added
- Removed
- Modified
- Copied
- Moved
django/branches/magic-removal/docs/db-api.txt
r2706 r2741 16 16 pub_date = models.DateTimeField() 17 17 expire_date = models.DateTimeField() 18 18 19 19 def __repr__(self): 20 20 return self.question … … 44 44 [What's up?, What's your name?] 45 45 46 How Queries Work46 How queries work 47 47 ================ 48 48 49 Querying in Django is based upon the construction and evaluation of Query 50 Sets. 51 52 A Query Set is a database-independent representation of a group of objects 53 that all meet a given set of criteria. However, the determination of which 49 Querying in Django is based upon the construction and evaluation of Query 50 Sets. 51 52 A Query Set is a database-independent representation of a group of objects 53 that all meet a given set of criteria. However, the determination of which 54 54 objects are actually members of the Query Set is not made until you formally 55 55 evaluate the Query Set. 56 56 57 57 To construct a Query Set that meets your requirements, you start by obtaining 58 an initial Query Set that describes all objects of a given type. This initial 59 Query Set can then be refined using a range of operations. Once you have 60 refined your Query Set to the point where it describes the group of objects 61 you require, it can be evaluated (using iterators, slicing, or one of a range 62 of other techniques), yielding an object or list of objects that meet the 58 an initial Query Set that describes all objects of a given type. This initial 59 Query Set can then be refined using a range of operations. Once you have 60 refined your Query Set to the point where it describes the group of objects 61 you require, it can be evaluated (using iterators, slicing, or one of a range 62 of other techniques), yielding an object or list of objects that meet the 63 63 specifications of the Query Set. 64 64 65 Obtaining an Initial QuerySet66 ============================= =67 68 Every model has at least one Manager; by default, the Manager is called 69 ``objects``. One of the most important roles of the Manager is as a source 70 of initial Query Sets. The Manager acts as a Query Set that describes all 71 objects of the type being managed; ``Polls.objects`` is the initial Query Set 65 Obtaining an initial QuerySet 66 ============================= 67 68 Every model has at least one Manager; by default, the Manager is called 69 ``objects``. One of the most important roles of the Manager is as a source 70 of initial Query Sets. The Manager acts as a Query Set that describes all 71 objects of the type being managed; ``Polls.objects`` is the initial Query Set 72 72 that contains all Polls in the database. 73 73 74 The initial Query Set on the Manager behaves in the same way as every other 75 Query Set in every respect except one - it cannot be evaluated. To overcome 74 The initial Query Set on the Manager behaves in the same way as every other 75 Query Set in every respect except one - it cannot be evaluated. To overcome 76 76 this limitation, the Manager Query Set has an ``all()`` method. The ``all()`` 77 method produces a copy of the initial Query Set - a copy that *can* be 77 method produces a copy of the initial Query Set - a copy that *can* be 78 78 evaluated:: 79 79 80 80 all_polls = Poll.objects.all() 81 81 82 See the `Managers`_ section of the Model API for more details on the role 82 See the `Managers`_ section of the Model API for more details on the role 83 83 and construction of Managers. 84 84 85 85 .. _Managers: http://www.djangoproject.com/documentation/model_api/#managers 86 86 87 Query Set Refinement88 =================== =89 90 The initial Query Set provided by the Manager describes all objects of a 91 given type. However, you will usually need to describe a subset of the 92 complete set of objects. 87 QuerySet refinement 88 =================== 89 90 The initial Query Set provided by the Manager describes all objects of a 91 given type. However, you will usually need to describe a subset of the 92 complete set of objects. 93 93 94 94 To create such a subset, you refine the initial Query Set, adding conditions 95 until you have described a set that meets your needs. The two most common 95 until you have described a set that meets your needs. The two most common 96 96 mechanisms for refining a Query Set are: 97 97 98 98 ``filter(**kwargs)`` 99 Returns a new Query Set containing objects that match the given lookup parameters. 99 Returns a new Query Set containing objects that match the given lookup parameters. 100 100 101 101 ``exclude(**kwargs)`` 102 102 Return a new Query Set containing objects that do not match the given lookup parameters. 103 103 104 Lookup parameters should be in the format described in "Field lookups" below. 104 Lookup parameters should be in the format described in "Field lookups" below. 105 105 106 106 The result of refining a Query Set is itself a Query Set; so it is possible to … … 112 112 pub_date__gte=datetime(2005,1,1)) 113 113 114 ...takes the initial Query Set, and adds a filter, then an exclusion, then 115 another filter to remove elements present in the initial Query Set. The 116 final result is a Query Set containing all Polls with a question that 114 ...takes the initial Query Set, and adds a filter, then an exclusion, then 115 another filter to remove elements present in the initial Query Set. The 116 final result is a Query Set containing all Polls with a question that 117 117 starts with "What", that were published between 1 Jan 2005 and today. 118 118 119 119 Each Query Set is a unique object. The process of refinement is not one 120 of adding a condition to the initial Query Set. Rather, each refinement 121 creates a separate and distinct Query Set that can be stored, used. and 120 of adding a condition to the initial Query Set. Rather, each refinement 121 creates a separate and distinct Query Set that can be stored, used. and 122 122 reused. For example:: 123 123 … … 126 126 q3 = q1.filter(pub_date__gte=datetime.now()) 127 127 128 will construct 3 Query Sets; a base query set containing all Polls with a 128 will construct 3 Query Sets; a base query set containing all Polls with a 129 129 question that starts with "What", and two subsets of the base Query Set (one 130 with an exlusion, one with a filter). The initial Query Set is unaffected by 130 with an exlusion, one with a filter). The initial Query Set is unaffected by 131 131 the refinement process. 132 132 133 133 It should be noted that the construction of a Query Set does not involve any 134 activity on the database. The database is not consulted until a Query Set is 134 activity on the database. The database is not consulted until a Query Set is 135 135 evaluated. 136 136 … … 201 201 Poll.objects.get(id__exact=14) 202 202 203 Multiple lookup parameters are allowed. When separated by commans, the list of 203 Multiple lookup parameters are allowed. When separated by commans, the list of 204 204 lookup parameters will be "AND"ed together:: 205 205 … … 210 210 ) 211 211 212 ...retrieves all polls published in January 2005 that have a question starting 212 ...retrieves all polls published in January 2005 that have a question starting 213 213 with "Would." 214 214 … … 233 233 ========== 234 234 235 Keyword argument queries are "AND"ed together. If you have more 236 complex query requirements (for example, you need to include an ``OR`` 235 Keyword argument queries are "AND"ed together. If you have more 236 complex query requirements (for example, you need to include an ``OR`` 237 237 statement in your query), you need to use ``Q`` objects. 238 238 239 A ``Q`` object (``django.db.models.Q``) is an object used to encapsulate a 240 collection of keyword arguments. These keyword arguments are specified in 241 the same way as keyword arguments to the basic lookup functions like get() 239 A ``Q`` object (``django.db.models.Q``) is an object used to encapsulate a 240 collection of keyword arguments. These keyword arguments are specified in 241 the same way as keyword arguments to the basic lookup functions like get() 242 242 and filter(). For example:: 243 243 244 244 Q(question__startswith='What') 245 245 246 is a ``Q`` object encapsulating a single ``LIKE`` query. ``Q`` objects can be 247 combined using the ``&`` and ``|`` operators. When an operator is used on two 246 is a ``Q`` object encapsulating a single ``LIKE`` query. ``Q`` objects can be 247 combined using the ``&`` and ``|`` operators. When an operator is used on two 248 248 ``Q`` objects, it yields a new ``Q`` object. For example the statement:: 249 249 250 250 Q(question__startswith='Who') | Q(question__startswith='What') 251 251 252 ... yields a single ``Q`` object that represents the "OR" of two 252 ... yields a single ``Q`` object that represents the "OR" of two 253 253 "question__startswith" queries, equivalent to the SQL WHERE clause:: 254 254 255 255 ... WHERE question LIKE 'Who%' OR question LIKE 'What%' 256 256 257 You can compose statements of arbitrary complexity by combining ``Q`` objects 257 You can compose statements of arbitrary complexity by combining ``Q`` objects 258 258 with the ``&`` and ``|`` operators. Parenthetical grouping can also be used. 259 259 260 One or more ``Q`` objects can then provided as arguments to the lookup 261 functions. If multiple ``Q`` object arguments are provided to a lookup 260 One or more ``Q`` objects can then provided as arguments to the lookup 261 functions. If multiple ``Q`` object arguments are provided to a lookup 262 262 function, they will be "AND"ed together. For example:: 263 263 … … 272 272 AND (pub_date = '2005-05-02' OR pub_date = '2005-05-06') 273 273 274 If necessary, lookup functions can mix the use of ``Q`` objects and keyword 275 arguments. All arguments provided to a lookup function (be they keyword 276 argument or ``Q`` object) are "AND"ed together. However, if a ``Q`` object is 277 provided, it must precede the definition of any keyword arguments. For 274 If necessary, lookup functions can mix the use of ``Q`` objects and keyword 275 arguments. All arguments provided to a lookup function (be they keyword 276 argument or ``Q`` object) are "AND"ed together. However, if a ``Q`` object is 277 provided, it must precede the definition of any keyword arguments. For 278 278 example:: 279 279 … … 304 304 .. _OR lookups examples page: http://www.djangoproject.com/documentation/models/or_lookups/ 305 305 306 Query 307 =================== =308 309 A Query Set must be evaluated to return the objects that are contained in the 306 QuerySet evaluation 307 =================== 308 309 A Query Set must be evaluated to return the objects that are contained in the 310 310 set. This can be achieved by iteration, slicing, or by specialist function. 311 311 … … 315 315 for p in Poll.objects.all(): 316 316 print p 317 317 318 318 will print all the Poll objects, using the ``__repr__()`` method of Poll. 319 319 320 320 A Query Set can also be sliced, using array notation:: 321 321 … … 324 324 every_second_poll = Poll.objects.all()[::2] 325 325 326 Query Sets are lazy objects - that is, they are not *actually* sets (or 326 Query Sets are lazy objects - that is, they are not *actually* sets (or 327 327 lists) that contain all the objects that they represent. Python protocol 328 328 magic is used to make the Query Set *look* like an iterable, sliceable … … 338 338 create an in-memory representation of every element of the list. 339 339 340 Caching and Query 341 ===================== =342 343 Each Query Set contains a cache. In a newly created Query Set, this cache 344 is unpopulated. When a Query Set is evaluated for the first time, Django 345 makes a database query to populate the cache, and then returns the results 346 that have been explicitly requested (e.g., the next element if iteration 340 Caching and QuerySets 341 ===================== 342 343 Each Query Set contains a cache. In a newly created Query Set, this cache 344 is unpopulated. When a Query Set is evaluated for the first time, Django 345 makes a database query to populate the cache, and then returns the results 346 that have been explicitly requested (e.g., the next element if iteration 347 347 is in use). Subsequent evaluations of the Query Set reuse the cached results. 348 348 349 This caching behavior must be kept in mind when using Query Sets. For 349 This caching behavior must be kept in mind when using Query Sets. For 350 350 example, the following will cause two temporary Query Sets to be created, 351 351 evaluated, and thrown away:: … … 355 355 356 356 On a small, low-traffic website, this may not pose a serious problem. However, 357 on a high traffic website, it effectively doubles your database load. In 358 addition, there is a possibility that the two lists may not be identical, 359 since a poll may be added or deleted by another user between making the two 360 requests. 357 on a high traffic website, it effectively doubles your database load. In 358 addition, there is a possibility that the two lists may not be identical, 359 since a poll may be added or deleted by another user between making the two 360 requests. 361 361 362 362 To avoid this problem, simply save the Query Set and reuse it:: … … 366 366 print [p for p in queryset] # Re-use the cache from the evaluation 367 367 368 Specialist Query Set Evaluation369 ============================== =370 371 The following specialist functions can also be used to evaluate a Query Set. 372 Unlike iteration or slicing, these methods do not populate the cache; each 373 time one of these evaluation functions is used, the database will be queried. 368 Specialist QuerySet evaluation 369 ============================== 370 371 The following specialist functions can also be used to evaluate a Query Set. 372 Unlike iteration or slicing, these methods do not populate the cache; each 373 time one of these evaluation functions is used, the database will be queried. 374 374 375 375 ``get(**kwargs)`` … … 410 410 411 411 >>> Poll.objects.latest() 412 What's up? 412 What's up? 413 413 >>> Poll.objects.latest('expire_date') 414 414 What's your name? … … 417 417 ===================== 418 418 419 When you define a relationship in a model (i.e., a ForeignKey, 419 When you define a relationship in a model (i.e., a ForeignKey, 420 420 OneToOneField, or ManyToManyField), Django uses the name of the 421 421 relationship to add a descriptor_ on every instance of the model. 422 422 This descriptor behaves just like a normal attribute, providing 423 access to the related object or objects. For example, 424 ``mychoice.poll`` will return the poll object associated with a specific 423 access to the related object or objects. For example, 424 ``mychoice.poll`` will return the poll object associated with a specific 425 425 instance of ``Choice``. 426 426 … … 429 429 Django also adds a descriptor for the 'other' side of the relationship - 430 430 the link from the related model to the model that defines the relationship. 431 Since the related model has no explicit reference to the source model, 432 Django will automatically derive a name for this descriptor. The name that 433 Django chooses depends on the type of relation that is represented. However, 431 Since the related model has no explicit reference to the source model, 432 Django will automatically derive a name for this descriptor. The name that 433 Django chooses depends on the type of relation that is represented. However, 434 434 if the definition of the relation has a `related_name` parameter, Django 435 435 will use this name in preference to deriving a name. 436 436 437 There are two types of descriptor that can be employed: Single Object 438 Descriptors and Object Set Descriptors. The following table describes 439 when each descriptor type is employed. The local model is the model on 440 which the relation is defined; the related model is the model referred 437 There are two types of descriptor that can be employed: Single Object 438 Descriptors and Object Set Descriptors. The following table describes 439 when each descriptor type is employed. The local model is the model on 440 which the relation is defined; the related model is the model referred 441 441 to by the relation. 442 442 … … 445 445 =============== ============= ============= 446 446 OneToOneField Single Object Single Object 447 447 448 448 ForeignKey Single Object Object Set 449 449 450 450 ManyToManyField Object Set Object Set 451 451 =============== ============= ============= 452 452 453 Single Object Descriptor453 Single object descriptor 454 454 ------------------------ 455 455 … … 464 464 mychoice.save() 465 465 466 Whenever a change is made to a Single Object Descriptor, save() 466 Whenever a change is made to a Single Object Descriptor, save() 467 467 must be called to commit the change to the database. 468 468 469 If no `related_name` parameter is defined, Django will use the 469 If no `related_name` parameter is defined, Django will use the 470 470 lower case version of the source model name as the name for the 471 related descriptor. For example, if the ``Choice`` model had 471 related descriptor. For example, if the ``Choice`` model had 472 472 a field:: 473 473 474 474 coordinator = models.OneToOneField(User) 475 475 476 476 ... instances of the model ``User`` would be able to call: 477 477 … … 481 481 By default, relations do not allow values of None; if you attempt 482 482 to assign None to a Single Object Descriptor, an AttributeError 483 will be thrown. However, if the relation has 'null=True' set 484 (i.e., the database will allow NULLs for the relation), None can 483 will be thrown. However, if the relation has 'null=True' set 484 (i.e., the database will allow NULLs for the relation), None can 485 485 be assigned and returned by the descriptor to represent empty 486 486 relations. … … 488 488 Access to Single Object Descriptors is cached. The first time 489 489 a descriptor on an instance is accessed, the database will be 490 queried, and the result stored. Subsequent attempts to access 490 queried, and the result stored. Subsequent attempts to access 491 491 the descriptor on the same instance will use the cached value. 492 492 493 Object Set Descriptor493 Object set descriptor 494 494 --------------------- 495 495 496 An Object Set Descriptor acts just like the Manager - as an initial Query 496 An Object Set Descriptor acts just like the Manager - as an initial Query 497 497 Set describing the set of objects related to an instance. As such, any 498 query refining technique (filter, exclude, etc) can be used on the Object 498 query refining technique (filter, exclude, etc) can be used on the Object 499 499 Set descriptor. This also means that Object Set Descriptor cannot be evaluated 500 500 directly - the ``all()`` method must be used to produce a Query Set that 501 501 can be evaluated. 502 502 503 If no ``related_name`` parameter is defined, Django will use the lower case 504 version of the source model name appended with `_set` as the name for the 505 related descriptor. For example, every ``Poll`` object has a ``choice_set`` 503 If no ``related_name`` parameter is defined, Django will use the lower case 504 version of the source model name appended with `_set` as the name for the 505 related descriptor. For example, every ``Poll`` object has a ``choice_set`` 506 506 descriptor. 507 507 508 The Object Set Descriptor has utility methods to add objects to the 508 The Object Set Descriptor has utility methods to add objects to the 509 509 related object set: 510 510 511 511 ``add(obj1, obj2, ...)`` 512 Add the specified objects to the related object set. 513 512 Add the specified objects to the related object set. 513 514 514 ``create(\**kwargs)`` 515 Create a new object, and put it in the related object set. See 515 Create a new object, and put it in the related object set. See 516 516 _`Creating new objects` 517 517 … … 520 520 521 521 ``remove(obj1, obj2, ...)`` 522 Remove the specified objects from the related object set. 523 522 Remove the specified objects from the related object set. 523 524 524 ``clear()`` 525 525 Remove all objects from the related object set. 526 527 These two removal methods will not exist on ForeignKeys where ``Null=False`` 526 527 These two removal methods will not exist on ForeignKeys where ``Null=False`` 528 528 (such as in the Poll example). This is to prevent database inconsistency - if 529 529 the related field cannot be set to None, then an object cannot be removed 530 from one relation without adding it to another. 530 from one relation without adding it to another. 531 531 532 532 The members of a related object set can be assigned from any iterable object. … … 536 536 537 537 If the ``clear()`` method is available, any pre-existing objects will be removed 538 from the Object Set before all objects in the iterable (in this case, a list) 539 are added to the choice set. If the ``clear()`` method is not available, all 540 objects in the iterable will be added without removing any existing elements. 538 from the Object Set before all objects in the iterable (in this case, a list) 539 are added to the choice set. If the ``clear()`` method is not available, all 540 objects in the iterable will be added without removing any existing elements. 541 541 542 542 Each of these operations on the Object Set Descriptor has immediate effect 543 543 on the database - every add, create and remove is immediately and 544 automatically saved to the database. 545 546 Relationships and Queries544 automatically saved to the database. 545 546 Relationships and queries 547 547 ========================= 548 548 549 549 When composing a ``filter`` or ``exclude`` refinement, it may be necessary to 550 include conditions that span relationships. Relations can be followed as deep 551 as required - just add descriptor names, separated by double underscores, to 550 include conditions that span relationships. Relations can be followed as deep 551 as required - just add descriptor names, separated by double underscores, to 552 552 describe the full path to the query attribute. The query:: 553 553 … … 555 555 556 556 ... is interpreted as 'get every Foo that has a name1 that has a name2 that 557 has a name3 that has an attribute with lookup matching value'. In the Poll 557 has a name3 that has an attribute with lookup matching value'. In the Poll 558 558 example:: 559 559 560 560 Choice.objects.filter(poll__slug__startswith="eggs") 561 561 562 ... describes the set of choices for which the related poll has a slug 563 attribute that starts with "eggs". Django automatically composes the joins 562 ... describes the set of choices for which the related poll has a slug 563 attribute that starts with "eggs". Django automatically composes the joins 564 564 and conditions required for the SQL query. 565 565 566 Specialist Query Sets Refinement567 =============================== =568 569 In addition to ``filter`` and ``exclude()``, Django provides a range of 570 Query Set refinement methods that modify the types of results returned by 566 Specialist QuerySets refinement 567 =============================== 568 569 In addition to ``filter`` and ``exclude()``, Django provides a range of 570 Query Set refinement methods that modify the types of results returned by 571 571 the Query Set, or modify the way the SQL query is executed on the database. 572 572 … … 574 574 ---------------------- 575 575 576 The results returned by a Query Set are automatically ordered by the ordering 577 tuple given by the ``ordering`` meta key in the model. However, ordering may be 576 The results returned by a Query Set are automatically ordered by the ordering 577 tuple given by the ``ordering`` meta key in the model. However, ordering may be 578 578 explicitly provided by using the ``order_by`` method:: 579 579 580 Poll.objects.filter(pub_date__year=2005, 580 Poll.objects.filter(pub_date__year=2005, 581 581 pub_date__month=1).order_by('-pub_date', 'question') 582 582 … … 600 600 -------------- 601 601 602 By default, a Query Set will not eliminate duplicate rows. This will not 602 By default, a Query Set will not eliminate duplicate rows. This will not 603 603 happen during simple queries; however, if your query spans relations, 604 604 or you are using a Values Query Set with a ``fields`` clause, it is possible 605 to get duplicated results when a Query Set is evaluated. 605 to get duplicated results when a Query Set is evaluated. 606 606 607 607 ``distinct()`` returns a new Query Set that eliminates duplicate rows from the 608 results returned by the Query Set. This is equivalent to a ``SELECT DISTINCT`` 609 SQL clause. 608 results returned by the Query Set. This is equivalent to a ``SELECT DISTINCT`` 609 SQL clause. 610 610 611 611 ``values(*fields)`` 612 612 -------------------- 613 613 614 Returns a Values Query Set - a Query Set that evaluates to a list of 615 dictionaries instead of model-instance objects. Each dictionary in the 616 list will represent an object matching the query, with the keys matching 614 Returns a Values Query Set - a Query Set that evaluates to a list of 615 dictionaries instead of model-instance objects. Each dictionary in the 616 list will represent an object matching the query, with the keys matching 617 617 the attribute names of the object. 618 618 … … 624 624 625 625 >>> Poll.objects.values() 626 [{'id': 1, 'slug': 'whatsup', 'question': "What's up?", 627 'pub_date': datetime.datetime(2005, 2, 20), 626 [{'id': 1, 'slug': 'whatsup', 'question': "What's up?", 627 'pub_date': datetime.datetime(2005, 2, 20), 628 628 'expire_date': datetime.datetime(2005, 3, 20)}, 629 {'id': 2, 'slug': 'name', 'question': "What's your name?", 630 'pub_date': datetime.datetime(2005, 3, 20), 629 {'id': 2, 'slug': 'name', 'question': "What's your name?", 630 'pub_date': datetime.datetime(2005, 3, 20), 631 631 'expire_date': datetime.datetime(2005, 4, 20)}] 632 632 >>> Poll.objects.values('id', 'slug') … … 634 634 635 635 A Values Query Set is useful when you know you're only going to need values 636 from a small number of the available fields and you won't need the 637 functionality of a model instance object. It's more efficient to select only 636 from a small number of the available fields and you won't need the 637 functionality of a model instance object. It's more efficient to select only 638 638 the fields you need to use. 639 639 … … 641 641 ----------------------------------- 642 642 643 Returns a Date Query Set - a Query Set that evaluates to a list of 644 ``datetime.datetime`` objects representing all available dates of a 643 Returns a Date Query Set - a Query Set that evaluates to a list of 644 ``datetime.datetime`` objects representing all available dates of a 645 645 particular kind within the contents of the Query Set. 646 646 … … 720 720 for injecting specific clauses into the SQL generated by a Query Set. 721 721 722 Note that by definition these extra lookups may not be portable to different 723 database engines (because you're explicitly writing SQL code) and should be 722 Note that by definition these extra lookups may not be portable to different 723 database engines (because you're explicitly writing SQL code) and should be 724 724 avoided if possible.: 725 725 … … 828 828 829 829 This is a safety mechanism to prevent you from accidentally requesting 830 ``Polls.objects.delete()``, and deleting *all* the polls. 830 ``Polls.objects.delete()``, and deleting *all* the polls. 831 831 832 832 If you *actually* want to delete all the objects, then you have to explicitly … … 857 857 ====================== 858 858 859 In addition to ``save()``, ``delete()``, a model object might get any or all 859 In addition to ``save()``, ``delete()``, a model object might get any or all 860 860 of the following methods: 861 861 … … 943 943 ``get_FOO_width()`` methods, where ``FOO`` is the name of the field. This 944 944 returns the height (or width) of the image, as an integer, in pixels. 945
