# Relations plugin for model builder
## Relation data type
The relation data type marks part of the metadata that will be filled with a related object.
Example usage - part of dataset model:
```yaml
primary-article:
type: relation
name: article
model: article
keys: ['metadata.title', 'metadata.authors']
```
The element "primary-article" will be connected to the article record. The record
class and properties will be taken from the "article" model
that is registered in "oarepo_models" entrypoint.
When returned to the user/serialized to ES, it will take the title and
author fields from the related model and copy them into the primary-article field.
It will automatically generate the following schema:
will generate:
```json5
// schema
{
"primary-article": {
"type": "object",
"properties": {
"id": {"type": "string"},
"@v": {"type": "string"},
"title": {}, // copied from registered article model
"authors": {} // copied from registered article model
}
}
}
```
```python
class Record:
# ...
relations = MultiRelationsField(
article=PIDRelation( # "name" from above
"...primary-article", # path inside the dataset model
"keys": ['metadata.title', 'metadata.authors'], # copied keys
pid_field: Article.pid # resolved model name and PID field
)
)
```
All arguments:
```yaml
primary-article:
type: relation
name: ...
model: ...
keys: [...]
model-class:
relation-classes:
list: PIDListRelation
nested: PIDNestedListRelation
single: PIDRelation
relation-class:
relation-args:
attrs: []
keys: []
_value_key_suffix: id
_clear_empty: true
cache_key:
value_check:
pid_field: model-class.pid
imports:
- import: invenio_records_resources.records.system_fields.relations.PIDRelation
alias: PIDRelation
```
| Field | Description |
|------------------|---------------|
| name | Relation name, will be used as param name inside RelationsField |
| model | Name of the referenced model - from oarepo.models entrypoint or passed on commandline via --include parameter |
| keys | Array of paths or dicts. If item is a path, that path will be copied from the referenced model. If it is dict it must contain the whole model definition. |
| model-class | Class representing the related model |
| relation-classes | If the field is not an array and not nested inside an array, "single" is used. If the field is an array "list" is used. If the field is inside an array field, "nested" is used |
| relation-class | can be used to override relation-classes |
| relation-args | A dictionary of arguments that will be passes to the relation class |
| imports | You can define your own imports/aliases here. The defaults are thise for list, nested and single relation classes |
## Internal relations
Sometimes it you might want to reference part of your document for indexing purposes etc. and not split the document into two records.
For these, internal relations can be used:
```yaml
properties:
metadata:
properties:
obj{}:
^id: anchor-obj
test: keyword
id: keyword
```
On object/array item, define the "id" field containing your "symbolic" name of the target of the relation.
Then the definition of the relation will look like:
```yaml
properties:
metadata:
properties:
internal-ref:
type: relation
model: "#anchor-obj"
keys: [id, test]
```
## Supported relations
See [referrer.yaml](https://github.com/oarepo/oarepo-model-builder-relations/blob/main/tests/referrer.yaml) for a list of supported relations.
Raw data
{
"_id": null,
"home_page": "https://github.com/oarepo/oarepo-model-builder-relations",
"name": "oarepo-model-builder-relations",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "",
"keywords": "invenio relations model builder",
"author": "Miroslav Simek",
"author_email": "simek.miroslav@techlib.cz",
"download_url": "https://files.pythonhosted.org/packages/c8/4b/f7bbfe74473a034812ab0580a0b637b38aaa0d3d04c99620c43a52687cbc/oarepo-model-builder-relations-4.0.10.tar.gz",
"platform": "any",
"description": "# Relations plugin for model builder\n\n## Relation data type\n\nThe relation data type marks part of the metadata that will be filled with a related object.\n\nExample usage - part of dataset model:\n\n```yaml\nprimary-article:\n type: relation\n name: article\n model: article\n keys: ['metadata.title', 'metadata.authors']\n```\n\nThe element \"primary-article\" will be connected to the article record. The record\nclass and properties will be taken from the \"article\" model\nthat is registered in \"oarepo_models\" entrypoint.\n\nWhen returned to the user/serialized to ES, it will take the title and\nauthor fields from the related model and copy them into the primary-article field.\n\nIt will automatically generate the following schema:\n\nwill generate:\n\n```json5\n// schema\n{\n \"primary-article\": {\n \"type\": \"object\",\n \"properties\": {\n \"id\": {\"type\": \"string\"},\n \"@v\": {\"type\": \"string\"},\n \"title\": {}, // copied from registered article model\n \"authors\": {} // copied from registered article model\n }\n }\n}\n```\n\n```python\nclass Record:\n # ...\n relations = MultiRelationsField(\n article=PIDRelation( # \"name\" from above\n \"...primary-article\", # path inside the dataset model\n \"keys\": ['metadata.title', 'metadata.authors'], # copied keys\n pid_field: Article.pid # resolved model name and PID field\n )\n )\n```\n\nAll arguments:\n\n```yaml\nprimary-article:\n type: relation\n name: ...\n model: ...\n keys: [...]\n model-class:\n relation-classes:\n list: PIDListRelation\n nested: PIDNestedListRelation\n single: PIDRelation\n relation-class:\n relation-args:\n attrs: []\n keys: []\n _value_key_suffix: id\n _clear_empty: true\n cache_key:\n value_check:\n pid_field: model-class.pid\n imports:\n - import: invenio_records_resources.records.system_fields.relations.PIDRelation\n alias: PIDRelation\n```\n\n\n| Field | Description |\n|------------------|---------------|\n| name | Relation name, will be used as param name inside RelationsField |\n| model | Name of the referenced model - from oarepo.models entrypoint or passed on commandline via --include parameter |\n| keys | Array of paths or dicts. If item is a path, that path will be copied from the referenced model. If it is dict it must contain the whole model definition. |\n| model-class | Class representing the related model |\n| relation-classes | If the field is not an array and not nested inside an array, \"single\" is used. If the field is an array \"list\" is used. If the field is inside an array field, \"nested\" is used |\n| relation-class | can be used to override relation-classes |\n| relation-args | A dictionary of arguments that will be passes to the relation class |\n| imports | You can define your own imports/aliases here. The defaults are thise for list, nested and single relation classes |\n\n\n## Internal relations\n\nSometimes it you might want to reference part of your document for indexing purposes etc. and not split the document into two records.\nFor these, internal relations can be used:\n\n```yaml\n\nproperties:\n metadata:\n properties:\n obj{}:\n ^id: anchor-obj\n test: keyword\n id: keyword\n```\n\nOn object/array item, define the \"id\" field containing your \"symbolic\" name of the target of the relation.\nThen the definition of the relation will look like:\n\n```yaml\nproperties:\n metadata:\n properties:\n internal-ref:\n type: relation\n model: \"#anchor-obj\"\n keys: [id, test]\n```\n\n## Supported relations\n\nSee [referrer.yaml](https://github.com/oarepo/oarepo-model-builder-relations/blob/main/tests/referrer.yaml) for a list of supported relations.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "\"A model builder plugin to reference relations\"",
"version": "4.0.10",
"project_urls": {
"Homepage": "https://github.com/oarepo/oarepo-model-builder-relations"
},
"split_keywords": [
"invenio",
"relations",
"model",
"builder"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e0037fdf5eb3a0026d23fee11a5c483e89b165f2ed96158f18de599b3de2b27c",
"md5": "5d4776f81ca0bdd2ab95ed3bcbd99ded",
"sha256": "85568dbc01b7954364c0899e47fb051f073906bef4d9f111e44d93e1f3e2f4d6"
},
"downloads": -1,
"filename": "oarepo_model_builder_relations-4.0.10-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "5d4776f81ca0bdd2ab95ed3bcbd99ded",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.9",
"size": 15647,
"upload_time": "2023-11-14T06:43:50",
"upload_time_iso_8601": "2023-11-14T06:43:50.376069Z",
"url": "https://files.pythonhosted.org/packages/e0/03/7fdf5eb3a0026d23fee11a5c483e89b165f2ed96158f18de599b3de2b27c/oarepo_model_builder_relations-4.0.10-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c84bf7bbfe74473a034812ab0580a0b637b38aaa0d3d04c99620c43a52687cbc",
"md5": "f1ad1b2375447c199c24748e77954624",
"sha256": "d639fac07b5ca5ae23dc602fcee12d155d8924cec1785548395ed3625babceed"
},
"downloads": -1,
"filename": "oarepo-model-builder-relations-4.0.10.tar.gz",
"has_sig": false,
"md5_digest": "f1ad1b2375447c199c24748e77954624",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 9641,
"upload_time": "2023-11-14T06:43:51",
"upload_time_iso_8601": "2023-11-14T06:43:51.659944Z",
"url": "https://files.pythonhosted.org/packages/c8/4b/f7bbfe74473a034812ab0580a0b637b38aaa0d3d04c99620c43a52687cbc/oarepo-model-builder-relations-4.0.10.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-14 06:43:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "oarepo",
"github_project": "oarepo-model-builder-relations",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "oarepo-model-builder-relations"
}
JSON
