bento_meta.mdb ============== .. py:module:: bento_meta.mdb .. autoapi-nested-parse:: bento_meta.mdb ============== This module contains :class:`MDB`, with machinery for efficiently querying a Neo4j instance of a Metamodel Database. Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/bento_meta/mdb/loaders/index /autoapi/bento_meta/mdb/mdb/index /autoapi/bento_meta/mdb/mdb_tools/index /autoapi/bento_meta/mdb/searchable/index /autoapi/bento_meta/mdb/writeable/index Classes ------- .. autoapisummary:: bento_meta.mdb.MDB bento_meta.mdb.SearchableMDB bento_meta.mdb.WriteableMDB Functions --------- .. autoapisummary:: bento_meta.mdb.load_mdf bento_meta.mdb.load_model bento_meta.mdb.load_model_statements bento_meta.mdb.make_nanoid bento_meta.mdb.read_txn bento_meta.mdb.read_txn_data bento_meta.mdb.read_txn_value Package Contents ---------------- .. py:function:: load_mdf(mdf: MDFProtocol, mdb: bento_meta.mdb.writeable.WriteableMDB, _commit: str | None = None) -> None Load an MDF object into an MDB instance. .. py:function:: load_model(model: bento_meta.model.Model, mdb: bento_meta.mdb.writeable.WriteableMDB, _commit: str | None = None) -> None Load a model object into an MDB instance. .. py:function:: load_model_statements(model: bento_meta.model.Model, _commit: str | None = None) -> list[minicypher.statement.Statement] Create Cypher statements from a model to load it de novo into an MDB instance. :param :class:`mdb.Model` model: Model instance for loading :param str _commit: 'Commit string' for marking entities in DB. If set, this will override _commit attributes already existing on Model entities. .. py:class:: MDB(uri: str | None = None, user: str | None = None, password: str | None = None) A class representing a Metamodel Database. .. py:attribute:: uri .. py:attribute:: user .. py:attribute:: password .. py:attribute:: driver :type: neo4j.Driver | None :value: None .. py:attribute:: models :type: dict[str, list[str]] .. py:attribute:: latest_version :type: dict[str, str | None] .. py:attribute:: _txfns .. py:method:: close() -> None Close the driver connection. .. py:method:: register_txfn(name: str, fn: collections.abc.Callable) -> None Register a transaction function with the class for later use. See https://neo4j.com/docs/api/python-driver/current/api.html#managed-transactions-transaction-functions :param name: Name to register the function under. :param fn: The transaction function to register. .. py:method:: get_model_info() -> tuple[str, None, str] Get models, versions, and latest versions from MDB Model nodes. .. py:method:: get_model_handles() -> list[str] Return a simple list of model handles available. Queries Model nodes (not model properties in Entity nodes). :returns: List of model handle strings. .. py:method:: get_model_versions(model: str) -> list[str] | None Get list of version strings present in database for a given model. :param model: Model handle to get versions for. :returns: List of version strings, or None if model not found. .. py:method:: get_latest_version(model: str) -> str | None Get the version string from Model node marked is_latest:True for a model handle. :param model: Model handle to get latest version for. :returns: Version string, or None if model not found. .. py:method:: get_model_nodes(model: str | None = None) -> list[dict[str, Any]] | None Return a list of dicts representing Model nodes. Returns all versions. :param model: Optional model handle to filter by. :returns: List of dicts representing Model nodes, or None if not found. .. py:method:: get_nodes_by_model(model: str | None = None, version: str | None = None) -> list[dict[str, Any]] | None Get all nodes for a given model. :param model: Model handle to get nodes for. If None, get all nodes in database. :param version: Version to filter by. If None, get nodes from model version marked is_latest:true. If '*', get nodes from all model versions. :returns: List of node dicts. .. py:method:: get_model_nodes_edges(model: str, version: str | None = None) -> list[dict[str, Any]] | None Get all node-relationship-node paths for a given model and version. :param model: Model handle to get paths for. :param version: Version to filter by. If None, use version marked is_latest:true for model. If '*', retrieve from all versions. :returns: List of path dicts. .. py:method:: get_node_edges_by_node_id(nanoid: str) -> list[dict[str, str]] Get incoming and outgoing relationship information for a node from its nanoid. :param nanoid: The nanoid of the node to get edges for. :returns: List of dicts with id, handle, model, version, near_type, far_type, rln, far_node. .. py:method:: get_node_and_props_by_node_id(nanoid: str) -> list[dict[str, Any]] | None Get a node and its properties, given the node nanoid. :param nanoid: The nanoid of the node to get. :returns: List with dict containing id, handle, model, version, node, props[]. .. py:method:: get_nodes_and_props_by_model(model: str | None = None, version: str | None = None) -> list[dict[str, Any]] | None Get all nodes with associated properties given a model handle. :param model: Model handle to get nodes for. If None, get all nodes with their properties. :param version: Version to filter by. If None, get nodes and props from model version marked is_latest:true. If '*', get nodes and props from all model versions. :returns: List of dicts with id, handle, model, version, props[]. .. py:method:: get_prop_node_and_domain_by_prop_id(nanoid: str) -> list[dict[str, Any]] | None Get a property, its node, and its value domain or value set of terms by nanoid. :param nanoid: The nanoid of the property to get. :returns: List with dict containing id, handle, model, version, value_domain, prop, node, value_set, terms[]. .. py:method:: get_valueset_by_id(nanoid: str) -> list[dict[str, Any]] | None Get a valueset with the properties that use it and the terms that constitute it. :param nanoid: The nanoid of the valueset to get. :returns: List with dict containing id, handle, url, terms[], props[]. .. py:method:: get_valuesets_by_model(model: str | None = None, version: str | None = None) -> list[dict[str, Any]] | None Get all valuesets that are used by properties in the given model and version. Gets all valuesets if model is None. Also returns list of properties using each valueset. :param model: Model handle to get valuesets for. If None, get all valuesets. :param version: Version to filter by. If None, get value sets associated with latest model version. If '*', get those associated with all versions. :returns: List of dicts with value_set, props[]. .. py:method:: get_term_by_id(nanoid: str) -> list[dict[str, Any]] | None Get a term having the given nanoid, with its origin. :param nanoid: The nanoid of the term to get. :returns: Dict with term, origin. .. py:method:: get_props_and_terms_by_model(model: str | None = None, version: str | None = None) -> list[dict[str, Any]] | None Get terms from valuesets associated with properties in a model and version. Gets all terms if model is None. :param model: Model handle to get props and terms for. If None, get all terms. :param version: Version to filter by. If None, get props and terms from the latest model version. If '*', get those from all versions. :returns: List of dicts with prop, terms[]. .. py:method:: get_origins() -> list[dict[str, Any]] | None Get all origins. :returns: List of origin dicts. .. py:method:: get_origin_by_id(oid: str) -> list[dict[str, Any]] | None Get an origin by nanoid. .. py:method:: get_tags_for_entity_by_id(nanoid: str) -> list[dict[str, Any]] | None Get all tags attached to an entity, given the entity's nanoid. :param nanoid: The nanoid of the entity to get tags for. :returns: List with dict containing model(str), tags[]. .. py:method:: get_tags_and_values(key: str | None = None) -> list[dict[str, Any]] | None Get all tag key/value pairs that are present in database. :param key: Optional key to filter by. :returns: values[]. :rtype: List of dicts with key(str) .. py:method:: get_entities_by_tag(key: str, value: str | None = None) -> list[dict[str, Any]] | None Get all entities, tagged with a given key or key:value pair. :param key: Tag key to filter by. :param value: Optional tag value to filter by. :returns: List of dicts with tag_key(str), tag_value(str), entity(str - label), entities[]. .. py:method:: get_with_statement(qry: str, parms: dict[str, Any] | None = None) -> list[dict[str, Any]] | None Run an arbitrary read statement and return data. .. py:function:: make_nanoid(alphabet: str = 'abcdefghijkmnopqrstuvwxyzABCDEFGHJKMNPQRSTUVWXYZ0123456789', size: int = 6) -> str Create a random nanoid and return it as a string. .. py:function:: read_txn(func: collections.abc.Callable[Concatenate[MDB, P], tuple[str, dict[str, Any] | None]]) -> collections.abc.Callable[Concatenate[MDB, P], list[neo4j.Record]] Decorate a query function to run a read transaction based on its query. Query function should return a tuple (qry_string, param_dict). :param func: The query function to decorate. :returns: Decorated function that returns list of driver Records. .. py:function:: read_txn_data(func: collections.abc.Callable[Concatenate[MDB, P], tuple[str, dict[str, Any] | None]]) -> collections.abc.Callable[Concatenate[MDB, P], list[dict[str, Any]] | None] Decorate a query function to run a read transaction based on its query. Query function should return a tuple (qry_string, param_dict). :param func: The query function to decorate. :returns: Decorated function that returns records as a list of simple dicts. .. py:function:: read_txn_value(func: collections.abc.Callable[Concatenate[MDB, P], tuple[str, dict[str, Any] | None, str]]) -> collections.abc.Callable[Concatenate[MDB, P], list[Any]] Decorate a query function to run a read transaction based on its query. Query function should return a tuple (qry_string, param_dict, values_key). :param func: The query function to decorate. :returns: Decorated function that returns list of values for key specified by query function. .. py:class:: SearchableMDB(uri: str | None = None, user: str | None = None, password: str | None = None) Bases: :py:obj:`bento_meta.mdb.MDB` :class:`bento_meta.mdb.MDB` subclass for searching fulltext indices on an MDB. .. py:attribute:: ftindexes .. py:method:: available_indexes() -> dict[str, dict[str, list[str]]] Fulltext indexes present in database. :returns: Dict mapping index_name to dict with entity_type (NODE|RELATIONSHIP), entities ([labels]), properties ([[props]]). .. py:method:: query_index(index: str, qstring: str, skip: str | None = None, limit: str | None = None) -> list[dict[str, Any]] | None Query a named fulltext index of nodes or relationships. :param index: Name of the fulltext index to query. :param qstring: Lucene query string. :param skip: Number of results to skip. :param limit: Maximum number of results to return. :returns: List of dicts with ent (entity dict), label, score (lucene score). .. py:method:: search_entity_handles(qstring: str) -> dict[str, list[dict[str, Any]]] | None Fulltext search of qstring over node, relationship, and property handles. :param qstring: Lucene query string. :returns: Dict with nodes, relationships, properties, each containing list of dicts with ent (entity dict) and score (lucene score). .. py:method:: search_terms(qstring: str, *, search_values: bool = True, search_definitions: bool = True) -> list[dict[str, Any]] | None Fulltext search for qstring over terms, by value, definition, or both (default). :param qstring: Lucene query string. :param search_values: If True, search term values. :param search_definitions: If True, search term definitions. :returns: List of dicts with ent (term dict) and score (lucene score). .. py:class:: WriteableMDB(uri: str | None = None, user: str | None = None, password: str | None = None) Bases: :py:obj:`bento_meta.mdb.mdb.MDB` :class:`bento_meta.mdb.MDB` subclass for writing to an MDB. .. py:method:: put_with_statement(qry: str, parms: dict[str, Any] | None = None) -> list[neo4j.Record] Run an arbitrary write statement. .. py:method:: put_term_with_origin(term: bento_meta.objects.Term, commit: str = '', _from: int = 1) -> list[neo4j.Record] Merge a bento-meta Term object, that has an Origin object set into an MDB. If a new term is created, assign a random 6-char nanoid to it. The Origin must already be represented in the database. :param term: Term object to merge. :param commit: GitHub commit SHA1 associated with the term (if any). :param _from: Source identifier. :returns: List of Records from the transaction.