DOC: Explain reference properties better

src/doc/tutorials/Data-Insertion.rst

@@ -83,33 +83,86 @@ corresponding python class:
 
 .. code:: python
 
-   rec = db.Record()
+   rec = db.Record() # rec.id is None
    rec.add_parent(name="Experiment")
    rec.add_property(name="date", value="2020-01-07")
    rec.insert()
+   print(rec.id) # rec.id set by the server
+
+Here, the record has a parent, the RecordType “Experiment”, and a Property date
+with a value ``"2020-01-07"``. After the successful insertion, our new Record is
+assigned an ``id`` by the server. In the following, let's assume this id to be
+``256``.
+
+Reference Properties
+--------------------
+
+Now suppose we want to insert an analysis that references the above experiment
+record as its source data. Since we know that the id of the experiment record is
+256, we can do the following:
+
+.. code:: python
+
+   ana = db.Record().add_parent(name="Analysis") # Create record and assign parent in one line
+   ana.add_property(name="Experiment", value=256)
+   ana.add_propertt(name="date", value="2020-01-08")
+   # possibly, add more properties here ...
+   ana.insert()
+
+The experiment record's id is used as the value of the ``Experiment`` property
+of the analysis Record (note how we use the RecordType ``Experiment`` as a
+``REFERENCE`` property here). Sending a CaosDB query like ``FIND RECORD
+Experiment WHICH IS REFERENCED BY A Analysis WITH date=2020-01-08`` would now
+return our original experiment record.
 
-Here, the record has a parent: The RecordType “Experiment”. And a
-Property: date.
+Equivalently, we can also use the Python object of the experiment record, i.e.,
+``rec`` as the value of the ``Experiment`` property:
 
-Note, that if you want to use a property that is not a primitive
-datatype like db.INTEGER and so on, you need to use the ID of the Entity
-that you are referencing.
+
+.. code:: python
+
+   ana = db.Record().add_parent(name="Analysis")
+   ana.add_property(name="Experiment", value=rec)
+   ana.add_propertt(name="date", value="2020-01-08")
+   # possibly, add more properties here ...
+   ana.insert()
+
+Finally, we can also insert both records at the same time using a
+``db.Container``:
 
 .. code:: python
 
    rec = db.Record()
    rec.add_parent(name="Experiment")
-   rec.add_property(name="report", value=235507)
-   rec.add_property(name="Analysis", value=230007)
-   rec.insert()
+   rec.add_property(name="date", value="2020-01-07")
+   ana = db.Record().add_parent(name="Analysis")
+   ana.add_property(name="Experiment", value=rec)
+   ana.add_propertt(name="date", value="2020-01-08")
+
+   cont = db.Container().extend([rec, ana]) # Add experiment and analysis
+                                            # records to our container
+   cont.insert() # Insert both at the same time, the CaosDB server will
+                 # resolve the reference upon insertion.
+
+All three ways result in an Analysis record which references an Experiment
+record.
+
+.. note::
+
+   Instead of using the ``Experiment`` RecordType as a ``REFERENCE`` porperty,
+   we can also create an actual property with data type ``Experiment``:
+   ``db.property(name="source", datatype="Experiment")``. Now you can add this
+   property to the analysis record with the experiment record as a value as
+   explained above. As a rule of thumbs, using a separate property for these
+   references is meaningful whenever you want to highlight that, e.g., this
+   particular experiment provided the source data for your analysis (as opposed
+   to another experiment that was used for validation).
 
-Of course, the IDs 235507 and 230007 need to exist in CaosDB. The first
-example shows how to use a db.REFERENCE Property (report) and the second
-shows that you can use any RecordType as Property to reference a Record
-that has such a parent.
+Advanced insertions
+-------------------
 
-Most Records do not have name however it can absolutely make sense. In
-that case use the name argument when creating it. Another useful feature
+Most Records do not have a name, however it can absolutely make sense to assign
+one. In that case use the name argument when creating it. Another useful feature
 is the fact that properties can have units:
 
 .. code:: python
@@ -134,7 +187,7 @@ container. E.g. if you have a python list ``analysis_results``:
 
    cont.insert()
 
-Useful is also, that you can insert directly tabular data.
+It may also be usefull to know that you can insert directly tabular data.
 
 .. code:: python
 
@@ -144,8 +197,8 @@ Useful is also, that you can insert directly tabular data.
    print(recs)
    recs.insert()
 
-With this example file
-`test.csv <uploads/4f2c8756a26a3984c0af09d206d583e5/test.csv>`__.
+Try it yourself with this example file
+`test.csv <uploads/4f2c8756a26a3984c0af09d206d583e5/test.csv>`__!
 
 List Properties
 ---------------