relationalai 0.13.0.dev0__py3-none-any.whl → 0.13.1__py3-none-any.whl

relationalai/semantics/__init__.py

@@ -1,153 +1,29 @@
-"""The RelationalAI semantics API.
-
-This module provides the core classes and functions for defining and querying
-semantic models.
+"""
+The RelationalAI Semantics Module.
 """
 
-from pandas import DataFrame
-from ..util.error import exc
-from ..util.docutils import include_in_docs
-from .frontend.base import (
-    Alias, CoreLibrary, Concept, Data, Distinct, Expression, Field, FieldRef, Fragment, Library,
-    Literal, Match, Model, New, Not, Chain, Property, Reading, Relationship, Statement, StatementAndSchema, Table, Union, Value,
-    Variable,
-)
-# populate the core library
-from .frontend import core
-
-# include this module in documentation
+# Mark this package's docstrings for inclusion
+# in automatically generated web documentation.
 __include_in_docs__ = True
 
-    # String, Integer, Int64, Int128, Float, Decimal, Bool,
-    # Date, DateTime,
-    # RawSource, Hash,
-    # select, where, require, define, distinct, union, data,
-    # rank, asc, desc,
-    # count, sum, min, max, avg, per,
-    # not_
-
-#------------------------------------------------------
-# Convenience model functions
-#------------------------------------------------------
-
-def _check_model():
-    if len(Model.all_models) == 0:
-        exc("Missing Model", "No Model has been defined. Please create a Model before using the semantics API.")
-    elif len(Model.all_models) > 1:
-        exc("Ambiguous model", "Multiple Models have been defined. Please use functions on the specific Model.")
-    return Model.all_models[0]
-
-@include_in_docs
-def select(*args:StatementAndSchema) -> Fragment:
-    """Return a selection fragment from the active model.
-
-    Parameters
-    ----------
-    *args : StatementAndSchema
-        Concepts, properties, relationships fields, expressions, or other
-        statements to select.
-
-    Returns
-    -------
-    Fragment
-        A composable query fragment representing the selection.
-
-    Examples
-    --------
-    Select a literal value and materialize the result as a pandas DataFrame:
-
-    >>> select(1).to_df()
-
-    Combine with filters to project properties of specific entities from the
-    current model:
-
-    >>> select(Person.name, Person.age) \
-    ...     .where(Person.age > 21).to_df()  # doctest: +SKIP
-    """
-    model = _check_model()
-    return model.select(*args)
-
-def define(*args:Statement):
-    model = _check_model()
-    return model.define(*args)
-
-def where(*args:Statement):
-    model = _check_model()
-    return model.where(*args)
-
-def require(*args:Statement):
-    model = _check_model()
-    return model.require(*args)
-
-def union(*args:Value):
-    model = _check_model()
-    return model.union(*args)
-
-def data(data: DataFrame | list[tuple] | list[dict], columns: list[str]|None = None):
-    model = _check_model()
-    return model.data(data, columns)
-
-def distinct(*args:Value):
-    model = _check_model()
-    return model.distinct(*args)
-
-def not_(*args:Value):
-    model = _check_model()
-    return model.not_(*args)
-
-def literal(value, type: Concept|None = None) -> Literal:
-    model = _check_model()
-    return Literal(value, model, type)
-
-#------------------------------------------------------
-# Convenience types
-#------------------------------------------------------
-Any = core.Any
-AnyEntity = core.AnyEntity
-TypeVar = core.TypeVar
-EntityTypeVar = core.EntityTypeVar
-Number = core.Number
-String = core.String
-Integer = core.Integer
-Int = core.Int
-Int64 = core.Int64
-Int128 = core.Int128
-Float = core.Float
-Decimal = core.Decimal
-Bool = core.Boolean
-Boolean = Bool
-Date = core.Date
-DateTime = core.DateTime
-# RawSource = core.RawSource
-# Hash = core.Hash
-
-#------------------------------------------------------
-# Convenience aggregates
-# NOTE: these should be deprecated
-#------------------------------------------------------
-
-from .std import aggregates as aggs
-
-rank = aggs.rank
-limit = aggs.limit
-asc = aggs.asc
-desc = aggs.desc
-count = aggs.count
-sum = aggs.sum
-min = aggs.min
-max = aggs.max
-avg = aggs.avg
-string_join = aggs.string_join
-per = aggs.per
-
-#------------------------------------------------------
-# Exports
-#------------------------------------------------------
+from .internal import (
+    Model, Concept, Relationship, RelationshipReading, Expression, Fragment, Error, Field,
+    AnyEntity, String, Integer, Int64, Int128, Float, Decimal, Bool,
+    Date, DateTime,
+    RawSource, Hash,
+    select, where, require, define, distinct, union, data,
+    rank, asc, desc,
+    count, sum, min, max, avg, per,
+    not_
+)
 
 __all__ = [
-    "Alias", "CoreLibrary", "Concept", "Data", "Distinct", "Expression", "Field", "FieldRef", "Fragment",
-    "Library", "Literal", "Match", "Model", "New", "Not", "Chain", "Property", "Reading", "Relationship",
-    "Table", "Union", "Value", "Variable", "core",
-
-    "select", "define", "where", "require", "union", "data", "not_",
+    "Model", "Concept", "Relationship", "RelationshipReading", "Expression", "Fragment", "Error", "Field",
+    "AnyEntity", "String", "Integer", "Int64", "Int128", "Float", "Decimal", "Bool",
+    "Date", "DateTime",
+    "RawSource", "Hash",
+    "select", "where", "require", "define", "distinct", "union", "data",
+    "rank", "asc", "desc",
+    "count", "sum", "min", "max", "avg", "per",
+    "not_",
 ]

relationalai/semantics/designs/query_builder/identify_by.md

@@ -0,0 +1,106 @@
+# Concept.identify_by
+
+We want to support reference schemes in the query builder directly, we do this by speficying a set of relationships that act as identifying information for a concept.
+
+## constructor variant
+
+```python
+SSN = Concept("SSN", extends=[String])
+person = Concept("Person", identify_by={
+    "ssn": SSN # can be a Concept, in which case we create a relationship {Person} has {ssn:SSN} behind the scenes
+})
+
+EmployeeNumber = Concept("EmployeeNumber", extends=[String])
+employee = Concept("Employee", extends=[Person], identify_by={
+    "employee_number": Relation("{Employee} is identified by {EmployeeNumber}"),
+})
+```
+
+## function variant
+
+```python
+Person = Concept("Person")
+Person.ssn = Relation("{Person} has {SSN}")
+Person.identify_by(Person.ssn)
+```
+
+## How this impacts `Concept.new`
+
+Once a concept has identifying relationships, values for them must always be provided when calling Concept.new. So given our definitions of Person above:
+
+```python
+Person.new() # raises an error, ssn is required
+Person.new(name="foo") # raises an error, ssn is required
+Person.new(ssn="123-45-6789") # works
+Person.new(ssn="123-45-6789", name="foo") # works
+```
+
+References schemes are inherited from parent concepts, so because Employee extends Person, we must provide both ssn and employee_number when creating an Employee:
+
+```python
+Employee.new(employee_number="123456") # raises an error, ssn is required
+Employee.new(ssn="123-45-6789") # raises an error, employee_number is required
+Employee.new(ssn="123-45-6789", employee_number="123456") # works
+```
+Internally, when calling Concept.new with a reference scheme, we must not only fill the values of the provided relationships, but also add this new identity to the population of the concept and if there are inherited reference schemes, we create the internal mappings from the child identity to the parent one.
+
+NOTE: the primary identity is always the highest ancestor in the hierarchy with a reference scheme. This means that while we hash employee_number to create a lookup to person, the identity of the employee will always be the hash of ssn. The QB deals with this mapping under the hood.
+
+```python
+Employee.new(ssn="123-45-6789", employee_number="123456")
+
+# during compilation will turn into the equivalent of:
+
+define(
+    p := construct(Person, ssn="123-45-6789"),
+    Person(p)
+    person_ssn(p, "123-45-6789"),
+    Employee(p),
+    employee_number(p, "123456"),
+    e := construct(Employee, employee_number="123456"),
+    employee_to_person(e, p),
+)
+```
+## How this impacts `Concept.filter_by`
+
+There are times where we might be working with an external source that only has a child identifier and not the parent one. While we require the parent identifier to be provided to add to the population, if we've already done that elsewhere, it's reasonable to get a reference to the parent identity from the child one. To do that we can use `Concept.filter_by`:
+
+```python
+define(
+    e := Employee.filter_by(employee_number="123456") # works assuming something has previousl added this employee_number to the population
+    e.salary(1000)
+)
+
+# during compilation will turn into the equivalent of:
+define(
+    e := construct(Employee, employee_number="123456"),
+    employee_to_person(e, p),
+    employee_salary(p, 1000)
+)
+```
+
+As stated previously, all references must map back to the parent identity and this employee id is just used to lookup the person id.
+
+## Implied constraints
+
+Any relationship that is used to identify a concept is mandatory (which is enforced directly by `.new()`) and also implies that the combination of identifying relationships must be unique. We can create those constraints like so when defining the reference scheme:
+
+```python
+# after adding the relationships to the concept
+rels = [getattr(self, rel) for rel in identify_by.keys()]
+self.require(*rels) # make the relationships mandatory
+self.require(distinct(*rels)) # ensure the relationships are unique (needs to be implemented)
+```
+
+If you were to write that by hand, it'd look something like this for Employee:
+
+```python
+Employee.require(Employee.ssn, Employee.employee_number)
+Employee.require(distinct(Employee.ssn, Employee.employee_number))
+```
+
+## Implementation notes
+
+We want to store the reference schemes on the concept itself and during the QB -> IR compilation, take them into account when we encounter either a `ConceptNew` (for the `.new(..)` case) or a `ConceptConstruct` (for the `.filter_by(..)` case). At that point in the compiler, we'd add the necessary mappings and handle parent reference schemes.
+
+Since we allow for multiple inheritance, the "primary" reference scheme is determined by doing depth first search on the parent types and taking the first ancestor with a reference scheme that we encounter. This means a user can control this by ordering their parents in `extends=[..]`.