diff --git a/CHANGELOG.md b/CHANGELOG.md
index 644309319714e9a0ccba3838116aed6f466725ce..3663667106caa05ea629b34e096f71ae36125d00 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -21,6 +21,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Documentation ###
+* [#83](https://gitlab.com/caosdb/caosdb-pylib/-/issues/83) - Improved
+ documentation on adding REFERENCE properties, both in the docstring of
+ `Entity.add_property` and in the data-insertion tutorial.
## [0.11.2] - 2023-03-14 ##
diff --git a/src/caosdb/common/models.py b/src/caosdb/common/models.py
index 08fcd0206b9df22902e80277d0e57b5f67c76db5..20e09810ba466d59cf7a82d68cad19fefb45b10b 100644
--- a/src/caosdb/common/models.py
+++ b/src/caosdb/common/models.py
@@ -461,18 +461,30 @@ class Entity:
unit=None, importance=None, inheritance=None): # @ReservedAssignment
"""Add a property to this entity.
- The first parameter is meant to identify the property entity. So the method expects an instance of
- Entity, an integer or a string here. The second parameter is the value of the new property. Any
- other named parameter may be passed by means of the keywwords. Accepted keywords are:
- id, name, description, importance, inheritance, datatype, and unit. Any other keyword will be
- ignored right now. But that may change in the future.
+ The first parameter is meant to identify the property entity either via
+ its id or name, or by providing the corresponding ``Entity`` Python
+ object. The second parameter is the value of the new property. Any other
+ named parameter may be passed by means of the keywwords. Accepted
+ keywords are: id, name, description, importance, inheritance, datatype,
+ and unit.
+
+ Notes
+ -----
+ If you want to add a property to an already existing entity, the
+ property ``id`` of that property needs to be specified before you send
+ the updated entity to the server.
Parameters
----------
- property : int, str, Property, optional
- An identifying parameter, by default None
- value : int, str, Property, optional
- The value of the new property, by default None
+ property : int, str, Entity, optional
+ An identifier for the property to be added, either its name, its id,
+ or the corresponding Entity Python object. If ``None``, either the
+ `name` or the `id` argument have to be specified explicitly. Default
+ is ``None``.
+ value : int, str, bool, datetime, Entity, or list of these types, optional
+ The value of the new property. In case of a reference to another
+ entity, this value may be the referenced entities id or the
+ ``Entity`` as a Python object. Default is None.
id : int, optional
Id of the property, by default None
name : str, optional
@@ -491,17 +503,64 @@ class Entity:
Returns
-------
Entity
+ This Entity object to which the new property has been added.
- Raises
- ------
+ Warns
+ -----
UserWarning
If the first parameter is None then id or name must be defined and not be None.
UserWarning
If the first parameter is an integer then it is interpreted as the id and id must be
undefined or None.
UserWarning
- If the first parameter is not None and neither an instance of Entity nor an integer it is
+ If the first parameter is not None and neither an instance of Entity nor an integer it is
interpreted as the name and name must be undefined or None.
+
+ Raises
+ ------
+ ValueError:
+ If you try to add an ``Entity`` object with File or Record role (or,
+ equivalently, a ``File`` or ``Record`` object) as a property, a
+ ``ValueError`` is raised.
+
+ Examples
+ --------
+ Add a simple integer property with the name ``TestProp`` and the value
+ 27 to a Record:
+
+ >>> import caosdb as db
+ >>> rec = db.Record(name="TestRec").add_parent(name="TestType")
+ >>> rec.add_property("TestProp", value=27) # specified by name, you could equally use the property's id if it is known
+
+ You can also use the Python object:
+
+ >>> prop = db.Property(name="TestProp", datatype=db.INTEGER)
+ >>> rec.add_property(prop, value=27) # specified via the Python object
+
+ In case of updating an existing Record, the Property needs to be
+ specified by id:
+
+ >>> rec = db.Record(name="TestRec").retrieve()
+ >>> prop2 = db.Property(name="OtherTestProp").retrieve()
+ >>> rec.add_property(id=prop2.id, value="My new value")
+ >>> rec.update()
+
+ Let's look at the more advanced example of adding a list of integers as
+ value of the above integer ``TestProp``:
+
+ >>> rec.add_property("TestProp", value=[27,28,29], datatype=db.LIST(db.INTEGER))
+
+ Note that since `TestProp` is a scalar integer Property, the datatype
+ `LIST<INTEGER>` has to be specified explicitly.
+
+ Finally, we can also add reference properties, specified by the RecordType of the referenced entity.
+
+ >>> ref_rec = db.Record(name="ReferencedRecord").add_parent(name="OtherRT")
+ >>> rec.add_property(name="OtherRT", value=ref_rec) # or value=ref_rec.id if ref_rec has one set by the server
+
+ See more on adding properties and inserting data in
+ https://docs.indiscale.com/caosdb-pylib/tutorials/Data-Insertion.html.
+
"""
pid = id
@@ -588,11 +647,13 @@ class Entity:
entity. If no `inheritance` is given, no properties will be inherited by the child.
This parameter is case-insensitive.
- Note that the behaviour is currently not yet specified when assigning parents to
- Records, it only works for inheritance of RecordTypes (and Properties).
-
- For more information, it is recommended to look into the
- :ref:`data insertion tutorial<tutorial-inheritance-properties>`.
+ Notes
+ -----
+ Note that the behaviour of the `inheritance` argument currently has not
+ yet been specified when assigning parents to Records, it only works for
+ inheritance of RecordTypes (and Properties). For more information, it is
+ recommended to look into the :ref:`data insertion
+ tutorial<tutorial-inheritance-properties>`.
Raises
------
@@ -1285,12 +1346,19 @@ out: List[Entity]
anyway. Set the flag 'strict' to True in order to force the server to take all warnings as errors.
This prevents the server from inserting this entity if any warning occurs.
- @param strict=False: Flag for strict mode.
- @param raise_exception_on_error=True: Flag to raise an
- exception when an error occurs.
- @param unique=True: Flag to only allow
- insertion of elements with unique names.
- @param flags: A dictionary of flags to be send with the insertion.
+ Parameters
+ ----------
+ strict : bool, optional
+ Flag for strict mode. Default is False.
+ raise_exception_on_error : bool, optional
+ Flag to raise an exception when an error occurs. Default is True.
+ unique : bool, optional
+ Flag to only allow insertion of elements with unique names. Default
+ is True.
+ flags : dict, optional
+ A dictionary of flags to be send with the insertion. Default is
+ None.
+
"""
return Container().append(self).insert(
@@ -1650,6 +1718,7 @@ class Property(Entity):
def add_property(self, property=None, value=None, id=None, name=None, description=None, datatype=None,
unit=None, importance=FIX, inheritance=FIX): # @ReservedAssignment
+ """See ``Entity.add_property``."""
return super().add_property(
property=property, id=id, name=name, description=description, datatype=datatype,
@@ -1783,6 +1852,7 @@ class RecordType(Entity):
def add_property(self, property=None, value=None, id=None, name=None, description=None, datatype=None,
unit=None, importance=RECOMMENDED, inheritance=FIX): # @ReservedAssignment
+ """See ``Entity.add_property``."""
return super().add_property(
property=property, id=id, name=name, description=description, datatype=datatype,
@@ -1838,6 +1908,7 @@ class Record(Entity):
def add_property(self, property=None, value=None, id=None, name=None, description=None, datatype=None,
unit=None, importance=FIX, inheritance=FIX): # @ReservedAssignment
+ """See ``Entity.add_property``."""
return super().add_property(
property=property, id=id, name=name, description=description, datatype=datatype,
@@ -1995,6 +2066,7 @@ class File(Record):
def add_property(self, property=None, id=None, name=None, description=None, datatype=None,
value=None, unit=None, importance=FIX, inheritance=FIX): # @ReservedAssignment
+ """See ``Entity.add_property``."""
return super().add_property(
property=property, id=id, name=name, description=description, datatype=datatype,
diff --git a/src/doc/tutorials/Data-Insertion.rst b/src/doc/tutorials/Data-Insertion.rst
index f2c7f830d1403fbdf45354d1f36a4ea339759058..9060345c836a43c57f8039d40020082a7f342b02 100644
--- a/src/doc/tutorials/Data-Insertion.rst
+++ b/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
---------------