Mangle Documentation

Mangle Datalog is a declarative logic programming language and deductive database system. It allows users to represent data as facts (logical statements similar to table rows) and define rules to compute new facts from existing ones.

Key features include:

• Declarative Syntax: Specify what you want rather than how to compute it.
• Structured Data: Support for complex types like lists, maps, and records (structs).
• Modularity: Programs can be split into modules.
• Type Safety: Benefits from static type checking and type inference.
• Advanced Querying: Supports aggregation and function calls.

Mangle is a programming language for deductive database programming, extending Datalog with features like aggregation, function calls, and optional type-checking. It is designed to represent and query data from multiple sources in a uniform way and can model domain knowledge using n-ary relations and structured data.

Key capabilities include:

• Simple Queries: Select-project-join relational queries.
• Aggregation: Grouping and performing calculations (e.g., fn:Count()).
• Recursive Queries: Defining rules that reference themselves to traverse graphs or hierarchies.
• Knowledge Graphs: Supporting arbitrary n-ary relations and property graphs.
• Temporal Knowledge Graphs: Associating facts with time intervals to query when truths are valid.

Mangle uses a 'positive datalog' language based on a logical data model. The core concepts are:

• Facts: The fundamental unit of data. All data is represented as facts.
• Base Facts (Extensional Relations): The initial set of facts that already exist in your system.
• Derived Facts (Intensional Relations): New facts created by applying rules to base facts.
• Evaluation: The process of applying rules to derive new facts.
• Knowledge Base: The complete set of both base and derived facts.

In this model, rules can only add facts; they can never remove them. This allows you to organize data freely without being constrained by the original source structure.

Mangle's API design is independent of the transport layer. You can wrap Mangle queries in a gRPC service. The service implementation should translate the wire format (e.g., Protobuf messages) into a Mangle query or program for evaluation.

// gRPC service definition
message ByAvRequest { repeated Availability availability = 1; }
message ByAvReply { repeated Volunteer reply = 1; }
service VolunteerQuery {
  rpc GetByMatchingAvailability (ByAvRequest) returns (ByAvReply) {}
}

In Mangle, you can define an 'extensional' database by listing facts directly in the source. Each fact is associated with a predicate (which acts like a table). Use constant symbols (e.g., /v/1, /monday) as identifiers to represent specific entities or values.

# Define entities
volunteer(/v/1).

# Define properties/facts
volunteer_name(/v/1, "Aisha Salehi").
volunteer_time_available(/v/1, /monday, /afternoon).
volunteer_skill(/v/1, /skill/admin).

To build the Mangle documentation locally, create and activate a Python virtual environment, then install sphinx and the required dependencies from the documentation directory's requirements.txt file.

python -m venv manglereadthedocs
. manglereadthedocs/bin/activate
pip install -U sphinx
READTHEDOCS=<path to readthedocs dir>
pip install -r ${READTHEDOCS}/requirements.txt

Because Datalog primarily deals with positive information, rows that do not meet a criteria (e.g., a project with zero developers) will not appear in a standard aggregation result. To include these 'zero' cases, you must use negation (!).

To identify entities that lack a specific property:

1. Define a helper table that identifies entities with the property.
2. Define a second table that selects all entities from a base set and uses ! to negate the helper table.

Constraint: Every variable mentioned in the head of a rule must be mentioned in at least one subquery that is not negated.

Example pattern for finding projects without developers:

project_with_developers(ProjectID) ⟸
  project_assignment(ProjectID, _, /software_development, _).

project_without_developers(ProjectID) ⟸
  project_name(ProjectID, _).
  !project_with_developers(ProjectID)

Before translating a Datalog program, rules must be rectified. Rectification involves rewriting rules that mention constants in the head or repeat variables by introducing fresh variables and explicit equations.

Example Transformation: Input rule:

knows(X, X) :- person(X).

Rectified rule:

knows(X, Y) :- person(X), Y = X.

Once rectified, the relational expression for an intensional predicate is the union of all its rules, processed inductively from level 0 (predicates referring only to extensional predicates) upwards.