| blob | 160ddc43e77d94e010d02eac70f8ebda49250ca6 |
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
31 <html>
32 <head>
35 </script>
41 (function(){function a(){this.t={};this.tick=function(c){this.t[c]=(new Date).getTime()};this.tick("start")}var b=new a;window.jstiming={Timer:a,load:b};if(window.external&&window.external.pageT)window.jstiming.pt=window.external.pageT;})();
46 //--></script>
50 <link rel="search" type="application/opensearchdescription+xml" title="Google Code" href="http://code.google.com/osd.xml">
52 <!--[if IE]><link rel="stylesheet" type="text/css" href="../../css/iehacks.css"><![endif]-->
58 </head>
65 <span>
67 <a id="lang-dropdown" class="dropdown" href="http://code.google.com" onclick="return false;"><img width="13" height="13" class="globeicon" src="../../images/globe2_small.png"
68 ><span style="text-decoration:underline">English</span> <span style="font-size:.75em;">▼</span></a>
70 </span>
71 </div>
81 </div>
87 <img src="../../images/code_logo.png" height="40" width="161" alt="Google Code" style="border:0;margin:3px 0 0 0;">
90 </a></div>
93 <form id="cse" action="http://www.google.com/cse" accept-charset="utf-8" class="gsc-search-box" onsubmit="executeGSearch(document.getElementById('gsearchInput').value); return false;">
94 <noscript>
96 </noscript>
98 <input id="gsearchInput" type="text" name="q" maxlength="2048" class="gsc-input" autocomplete="off" title="Google Code Search" style="width:345px">
100 <input title="Search" id="gsearchButton" class="gsc-search-button" name="sa" value="Search" type="submit">
102 </div>
103 </form>
122 </li>
126 </li>
129 <a href="../kb/index.html" title="Answers to frequently asked questions about Google App Engine">FAQ</a>
130 </li>
133 <a href="index.html" class="selected" title="Focused articles and tutorials for Google App Engine developers">Articles</a>
134 </li>
136 <li>
138 </li>
140 <li>
142 </li>
144 <li>
146 </li>
148 <li>
150 </li>
153 </ul>
160 <ul>
164 <li><a href="../business/index.html">App Engine for Business</a> <sup class="new">New!</sup></li>
165 </ul>
167 <ul>
169 <ul>
172 <ul>
178 <li><a href="../docs/java/gettingstarted/usingdatastore.html">Using the Datastore with JDO</a></li>
182 </ul>
183 </li>
185 <ul>
187 <li><a href="../docs/python/gettingstarted/devenvironment.html">The Development Environment</a></li>
189 <li><a href="../docs/python/gettingstarted/usingwebapp.html">Using the webapp Framework</a></li>
191 <li><a href="../docs/python/gettingstarted/handlingforms.html">Handling Forms With webapp</a></li>
197 </ul>
198 </li>
199 </ul>
200 </li>
201 </ul>
203 <ul>
205 <ul>
209 <ul>
213 <li><a href="../docs/java/datastore/creatinggettinganddeletingdata.html">Creating, Getting and Deleting Data</a></li>
219 <li><a href="../docs/java/javadoc/com/google/appengine/api/datastore/package-summary.html">Low-level API</a></li>
221 </ul>
222 </li>
224 <ul>
226 <ul>
229 <ul>
230 <li><a href="../docs/java/javadoc/com/google/appengine/api/blobstore/package-summary.html">API Reference</a></li>
231 </ul>
232 </li>
234 </ul>
235 </li>
237 <ul>
239 <li><a href="../docs/java/javadoc/com/google/appengine/api/images/package-summary.html">API Reference</a></li>
241 </ul>
242 </li>
244 <ul>
248 <li><a href="../docs/java/javadoc/com/google/appengine/api/mail/package-summary.html">Low-level API</a></li>
250 </ul>
251 </li>
253 <ul>
256 <li><a href="../docs/java/javadoc/com/google/appengine/api/memcache/package-summary.html">Low-level API</a></li>
258 </ul>
259 </li>
261 <ul>
265 <li><a href="../docs/java/javadoc/com/google/appengine/api/NamespaceManager.html">API Reference</a>
267 </ul>
268 </li>
270 <ul>
272 <li><a href="../docs/java/javadoc/com/google/appengine/api/oauth/package-summary.html">API Reference</a></li>
275 </ul>
276 </li>
278 <ul>
280 <li><a href="../docs/java/javadoc/com/google/appengine/api/labs/taskqueue/package-summary.html">API Reference</a></li>
282 </ul>
283 </li>
285 <ul>
288 <li><a href="../docs/java/javadoc/com/google/appengine/api/urlfetch/package-summary.html">Low-level API</a></li>
290 </ul>
291 </li>
293 <ul>
295 <li><a href="../docs/java/javadoc/com/google/appengine/api/users/package-summary.html">API Reference</a></li>
297 </ul>
298 </li>
300 <ul>
302 <li><a href="../docs/java/javadoc/com/google/appengine/api/xmpp/package-summary.html">API Reference</a></li>
304 </ul>
305 </li>
306 </ul>
307 </li>
311 <ul>
319 </ul>
320 </li>
322 <ul>
329 </ul>
330 </li>
332 <ul>
338 <ul>
340 </ul>
341 </li>
344 </ul>
345 </li>
347 <ul>
348 <li><a href="../docs/java/howto/maintenance.html">Handling Scheduled Maintenance Periods</a></li>
350 </ul>
351 </li>
353 </ul>
354 </li>
355 </ul>
357 <ul>
359 <ul>
363 <ul>
366 <li><a href="../docs/python/datastore/creatinggettinganddeletingdata.html">Creating, Getting and Deleting Data</a></li>
370 <li><a href="../docs/python/datastore/typesandpropertyclasses.html">Types and Property Classes</a></li>
375 <ul>
385 </ul>
386 </li>
388 </ul>
389 </li>
391 <ul>
393 <ul>
396 <ul>
402 </ul>
403 </li>
405 </ul>
406 </li>
408 <ul>
413 <ul>
417 </ul>
418 </li>
420 </ul>
421 </li>
423 <ul>
429 <ul>
434 </ul>
435 </li>
437 </ul>
438 </li>
440 <ul>
444 <ul>
447 </ul>
448 </li>
450 </ul>
451 </li>
453 <ul>
455 <li><a href="../docs/python/multitenancy/multitenancy.html">Multitenancy with Namespaces</a></li>
457 <li>Reference
458 <ul>
461 </ul>
462 </li>
464 </ul>
465 </li>
467 <ul>
470 <ul>
473 </ul>
474 </li>
476 </ul>
477 </li>
479 <ul>
482 <ul>
487 </ul>
488 </li>
490 </ul>
491 </li>
493 <ul>
496 <ul>
501 </ul>
502 </li>
504 </ul>
505 </li>
507 <ul>
514 <ul>
518 </ul>
519 </li>
521 </ul>
522 </li>
524 <ul>
527 <ul>
531 </ul>
532 </li>
534 </ul>
535 </li>
536 </ul>
537 </li>
539 <ul>
546 </ul>
547 </li>
549 <ul>
554 <ul>
559 <li><a href="../docs/python/tools/webapp/buildingtheresponse.html">Building the Response</a></li>
560 <li><a href="../docs/python/tools/webapp/redirects.html">Redirects, Headers and Status Codes</a></li>
564 <ul>
571 </ul>
572 </li>
574 </ul>
575 </li>
579 </ul>
580 </li>
582 <ul>
584 <li><a href="../docs/python/howto/maintenance.html">Handling Scheduled Maintenance Periods</a></li>
586 </ul>
587 </li>
589 </ul>
590 </li>
591 </ul>
593 <ul>
595 <ul>
600 </ul>
601 </li>
602 </ul>
604 <ul>
606 <ul>
614 <li>Launcher Code
615 <ul>
618 </ul>
619 </li>
621 </ul>
622 </li>
623 </ul>
625 <ul>
627 <li><a href="http://code.google.com/p/googleappengine/wiki/SdkReleaseNotes">Release Notes: Python</a></li>
628 <li><a href="http://code.google.com/p/googleappengine/wiki/SdkForJavaReleaseNotes">Release Notes: Java</a></li>
630 </ul>
633 </div>
647 <p class="note" align="center">This is one of a <a href="datastore/overview.html">series</a> of in-depth articles discussing App Engine's datastore. To see the other articles in the series, see <a href="#related">Related links</a>.</p>
649 <p>Sure, the Getting Started Guide tells you what you need to know in order to fill properties for a simple AppEngine model, but it's going to take more than that if you want to be able to represent real world concepts in the datastore. Whether you are new to web application development, or are used to working with SQL databases, this article is for those people who are ready to take a step into the next dimension of AppEngine data representation.</p>
651 <p>Imagine you are building a snazzy new web application that includes an address book where users can store their contacts. For each contact the user stores, you want to capture the contacts name, birthday (which they mustn't forget!) their address, telephone number and company they work for.</p>
652 <p>When the user wants to add an address, they enter the information in to a form and the form saves the information in a model that looks something like this:</p>
655 # Basic info.
656 name = db.StringProperty()
657 birth_day = db.DateProperty()
659 # Address info.
660 address = db.PostalAddressProperty()
662 # Phone info.
663 phone_number = db.PhoneNumberProperty()
665 # Company info.
666 company_title = db.StringProperty()
667 company_name = db.StringProperty()
668 company_description = db.StringProperty()
669 company_address = db.PostalAddressProperty()
670 </pre>
671 <p>That's great, your users immediately begin to use their address book and soon the datastore starts to fill up. Not long after the deployment of your new application you hear from someone that they are not happy that there is only one phone number. What if they want to storesomeone's work telephone number in addition to their home number? No problem you think, you can just add a work phone number to your structure. You change your data structure to look more like this:</p>
673 phone_number = db.PhoneNumberProperty()
674 work_phone_number = db.PhoneNumberProperty()
675 </pre>
676 <p>Update the form with the new field and you are back in business. Soon after redeploying your application, you get a number of new complaints. When they see the new phone number field, people start asking for even more fields. Some people want a fax number field, others want a mobile field. Some people even want more than one mobile field (boy modern life sure is hectic)! You could add another field for fax, and another for mobile, maybe two. What about if people have three mobile phones? What if they have ten? What if someone invents a phone for a place you've never thought of?</p>
679 <p>The answer is to allow users to assign as many phone numbers to each of their contacts as they like. To do this, you need to model the phone numbers in their own class and have a way of associating many phone numbers to a single Contact. You can easily model the one to many relationship using ReferenceProperty. Here is a candidate for this new class:</p>
682 # Basic info.
683 name = db.StringProperty()
684 birth_day = db.DateProperty()
686 # Address info.
687 address = db.PostalAddressProperty()
689 <b> # The original phone_number property has been replaced by
690 # an implicitly created property called 'phone_numbers'.</b>
692 # Company info.
693 company_title = db.StringProperty()
694 company_name = db.StringProperty()
695 company_description = db.StringProperty()
696 company_address = db.PostalAddressProperty()
698 <b>class PhoneNumber(db.Model):
699 contact = db.ReferenceProperty(Contact,
700 collection_name='phone_numbers')
701 phone_type = db.StringProperty(
702 choices=('home', 'work', 'fax', 'mobile', 'other'))
703 number = db.PhoneNumberProperty()</b>
704 </pre>
705 <p>The key to making all this work is the <code>contact</code> property. By defining it as a <code>ReferenceProperty</code>, you have created a property that can only be assigned values of type Contact. Every time you define a reference property, it creates an implicit collection property on the referenced class. By default, this collection is called <code><i><name-of-class></i>_set</code>. In this case, it would make a property <code>Contact.phonenumber_set</code>. However, it is probably more intuitive to call that attribute <code>phone_numbers</code>. You over-rode this default name using the <code>collection_name</code> keyword parameter to <code>ReferenceProperty</code>.</p>
706 <p>Creating the relationship between a contact and one of its phone numbers is easy to do. Let's say you have a contact named "Scott" who has a home phone and a mobile phone. You populate his contact info like this:</p>
708 scott.put()
709 PhoneNumber(contact=scott,
710 phone_type='home',
712 PhoneNumber(contact=scott,
713 phone_type='mobile',
715 </pre>
716 <p>Because <code>ReferenceProperty</code> creates this special property on <code>Contact</code>, it makes it very easy to retrieve all the phone numbers for a given person. If you wanted to print all the phone numbers for a given person, you can do it like this:</p>
718 print
719 for phone in scott.phone_numbers:
720 print '%s: %s' % (phone.phone_type, phone.number)
721 </pre>
725 </pre>
726 <p class="note"><b>Note:</b> The order of the output might be different as by default there is no ordering in this kind of relationship.</p>
727 <p>The <code>phone_numbers</code> virtual attribute is a <code>Query</code> instance, meaning that you can use it to further narrow down and sort the collection associated with the <code>Contact</code>. For example, if you only want to get the home phone numbers, you can do this:</p>
729 <p>When Scott loses his phone, it's easy enough to delete that record. Just delete the PhoneNumber instance and it can no longer be queried for:</p>
730 <pre class="prettyprint">scott.phone_numbers.filter('phone_type =', 'home').get().delete()</pre>
732 <p>One thing you would like to do is provide the ability for people to organize their contacts in to groups. They might make groups like "Friends", "Co-workers" and "Family". This would allow users to use these groups to perform actions en masse, such as maybe sending an invitation to all their friends for a hack-a-thon. Let's define a simple <code>Group</code> model like this:</p>
735 name = db.StringProperty()
736 description = db.TextProperty()
737 </pre>
738 <p>You could make a new <code>ReferenceProperty</code> on <code>Contact</code> called group. However, this would allow contacts to be part of only one group at a time. For example, someone might include some of their co-workers as friends. You need a way to represent many-to-many relationships.</p>
742 # User that owns this entry.
743 owner = db.UserProperty()
745 # Basic info.
746 name = db.StringProperty()
747 birth_day = db.DateProperty()
749 # Address info.
750 address = db.PostalAddressProperty()
752 # Company info.
753 company_title = db.StringProperty()
754 company_name = db.StringProperty()
755 company_description = db.StringProperty()
756 company_address = db.PostalAddressProperty()
758 <b> # Group affiliation
759 groups = db.ListProperty(db.Key)</b>
760 </pre>
763 mary = Contact.gql("WHERE name = 'Mary'").get()
764 if friends.key() not in mary.groups:
765 mary.groups.append(friends.key())
766 mary.put()
767 </pre>
768 <p>To get all the members of a group, you can execute a simple query. It might help to add a helper function to the <code>Group</code> entity:</p>
770 name = db.StringProperty()
771 description = db.TextProperty()
773 <b> @property
774 def members(self):
776 </pre>
777 <p>There are a few limitations to implementing many-to-many relationships this way. First, you must explicitly retrieve the values on the side of the collection where the list is stored since all you have available are <code>Key</code> objects. Another more important one is that you want to avoid storing overly large lists of keys in a <code>ListProperty</code>. This means you should place the list on side of the relationship which you expect to have fewer values. In the example above, the <code>Contact</code> side was chosen because a single person is not likely to belong to too many groups, whereas in a large contacts database, a group might contain hundreds of members.</p>
779 <p>One of your users is a big time saleswoman and knows teams of people in just one company. She is finding it very tedious to have to enter the same information about the same company again and again. Couldn't there be a way to specify a company once and then associate them with each person? If it were that simple, it would merely be necessary to have a one-to-many relationship between <code>Contact</code> and <code>Company</code>, but it's more complicated than that. Some of her contacts are contractors that work at more than one company and have different titles in each. What now?</p>
780 <p>You need a many-to-many relationship that can describe some additional information about that relationship. To accomplish this, you can use another <code>Model</code> to describe the relationship:</p>
782 # User that owns this entry.
783 owner = db.UserProperty()
785 # Basic info.
786 name = db.StringProperty()
787 birth_day = db.DateProperty()
789 # Address info.
790 address = db.PostalAddressProperty()
792 <b> # The original organization properties have been replaced by
793 # an implicitly created property called 'companies'. </b>
795 # Group affiliation
796 groups = db.ListProperty(db.Key)
798 <b>class Company(db.Model):
799 name = db.StringProperty()
800 description = db.StringProperty()
801 company_address = db.PostalAddressProperty()
803 class ContactCompany(db.Model):
804 contact = db.ReferenceProperty(Contact,
805 required=True,
806 collection_name='companies')
807 company = db.ReferenceProperty(Company,
808 required=True,
809 collection_name='contacts')
810 title = db.StringProperty()</b>
811 </pre>
814 google = Company.gql("name = 'Google'").get()
815 ContactCompany(contact=mary,
816 company=google,
817 title='Engineer').put()</pre>
818 <p>In addition to being able to being able to store information about a relationship, using this method has the advantage over the list-of-keys method in that you can have large collections on either side of the relationship. However, you need to be very careful because traversing the connections of a collection will require more calls to the datastore. Use this kind of many-to-many relationship only when you really need to, and do so with care to the performance of your application.</p>
820 <p>App Engine allows the creation of easy to use relationships between datastore entities which can represent real-world things and ideas. Use <code>ReferenceProperty</code> when you need to associate an arbitrary number of repeated types of information with a single entity. Use key-lists when you need to allow lots of different objects to share other instances between each other. You will find that these two approaches will provide you with most of what you need to create the model behind great applications.</p>
824 <ul>
833 </ul>
836 </div>
837 </div>
851 Except as otherwise <a
858 <!-- <rdf:RDF xmlns="http://web.resource.org/cc/"
859 xmlns:dc="http://purl.org/dc/elements/1.1/"
860 xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
861 <Work rdf:about="">
862 <license rdf:resource="http://creativecommons.org/licenses/by/3.0/" />
863 </Work>
864 <License rdf:about="http://creativecommons.org/licenses/by/3.0/">
865 <permits rdf:resource="http://web.resource.org/cc/Reproduction"/>
866 <permits rdf:resource="http://web.resource.org/cc/Distribution"/>
867 <requires rdf:resource="http://web.resource.org/cc/Notice"/>
868 <requires rdf:resource="http://web.resource.org/cc/Attribution"/>
869 <permits rdf:resource="http://web.resource.org/cc/DerivativeWorks"/>
870 </License>
871 </rdf:RDF> -->
872 </div>
873 Java is a registered trademark of Sun Microsystems, Inc.</div>
880 <br> <br>
881 Google Code offered in:
890 </div>
912 );
921 })();
922 </script>
927 </body>
928 </html>