{
"many" => attr.cardinality = AttributeCardinality::Many,
"history" => attr.with_history = true,
"no_history" => attr.with_history = false,
- "identity" => attr.indexing = AttributeIndex::Identity,
"index" => attr.indexing = AttributeIndex::Indexed,
"no_index" => attr.indexing = AttributeIndex::None,
"unique" => attr.indexing = AttributeIndex::Unique,
diff --git a/src/runtime/db.rs b/src/runtime/db.rs
index 84f5b510..9c6332a9 100644
--- a/src/runtime/db.rs
+++ b/src/runtime/db.rs
@@ -467,6 +467,7 @@ impl Db {
pub(crate) fn remove_relation(&self, name: &Symbol) -> Result<()> {
let mut tx = self.transact_write()?;
let (lower, upper) = tx.destroy_relation(name)?;
+ tx.commit_tx("", false)?;
self.db.range_del(&lower, &upper, Snd)?;
Ok(())
}
diff --git a/tests/air_routes.rs b/tests/air_routes.rs
index b4025fea..f1b57c1a 100644
--- a/tests/air_routes.rs
+++ b/tests/air_routes.rs
@@ -32,15 +32,15 @@ fn air_routes() -> Result<()> {
:schema
put country {
- code: string identity,
+ code: string unique,
desc: string
}
put continent {
- code: string identity,
+ code: string unique,
desc: string
}
put airport {
- iata: string identity,
+ iata: string unique,
icao: string index,
city: string index,
desc: string,
diff --git a/tests/simple.rs b/tests/simple.rs
index 3065bc8a..784605af 100644
--- a/tests/simple.rs
+++ b/tests/simple.rs
@@ -30,7 +30,7 @@ fn simple() {
r#"
:schema
put person {
- id: string identity,
+ id: string unique,
first_name: string index,
last_name: string index,
age: int,
diff --git a/tutorial/2-pilgrim.ipynb b/tutorial/2-pilgrim.ipynb
index 07916f4d..46816e2d 100644
--- a/tutorial/2-pilgrim.ipynb
+++ b/tutorial/2-pilgrim.ipynb
@@ -27,12 +27,12 @@
},
{
"cell_type": "markdown",
- "source": "## Stored",
+ "source": "## Stored relations",
"metadata": {}
},
{
"cell_type": "markdown",
- "source": "An obvious shortcoming of our previous acrobatics is that we have to carry around our love triangles network and enter it anew for every query, which leads to rapid deterioration of the `CTRL`, `C` and `V` on the keyboard. So let's fix that first.",
+ "source": "An obvious shortcoming of our previous acrobatics is that we have to carry around our love triangles network and enter it anew for every query, which leads to rapid deterioration of the `CTRL`, `C` and `V` keys. So let's fix that:",
"metadata": {}
},
{
@@ -41,26 +41,381 @@
"metadata": {
"trusted": true
},
- "execution_count": 10,
+ "execution_count": 59,
"outputs": [
{
- "execution_count": 10,
+ "execution_count": 59,
"output_type": "execute_result",
"data": {
- "text/html": "eval::stored_relation_conflict\n\n × Stored relation triangles conflicts with an existing one\n ╭─[9:1]\n 9 │ \n 10 │ :relation create triangles\n · ─────────\n ╰────\n
"
+ "text/html": "{\n "relation": "OK",\n "time_taken": 1\n}"
},
"metadata": {}
}
]
},
+ {
+ "cell_type": "markdown",
+ "source": "We have the _query directive_ `:relation create` together with a normal query. The results will then be stored on your disk with the name `triangles` instead of returned to you.",
+ "metadata": {}
+ },
+ {
+ "cell_type": "markdown",
+ "source": "You will receive an error if you try to run this script twice. In which case don't worry and continue.",
+ "metadata": {}
+ },
+ {
+ "cell_type": "markdown",
+ "source": "Stored relations are safe from restarts and power failures. Let's query against it:",
+ "metadata": {}
+ },
+ {
+ "cell_type": "code",
+ "source": "?[a, b] := :triangles[a, b]",
+ "metadata": {
+ "trusted": true
+ },
+ "execution_count": 60,
+ "outputs": [
+ {
+ "execution_count": 60,
+ "output_type": "execute_result",
+ "data": {
+ "text/html": "| a | b |
| alice | eve |
| bob | alice |
| charlie | eve |
| david | george |
| eve | alice |
| eve | bob |
| eve | charlie |
| george | george |
Took 0ms{\n "relation": "OK",\n "time_taken": 0\n}"
+ },
+ "metadata": {}
+ }
+ ]
+ },
+ {
+ "cell_type": "code",
+ "source": "?[a, b] := :triangles[a, b]",
+ "metadata": {
+ "trusted": true
+ },
+ "execution_count": 62,
+ "outputs": [
+ {
+ "execution_count": 62,
+ "output_type": "execute_result",
+ "data": {
+ "text/html": "| a | b |
| alice | eve |
| bob | alice |
| charlie | eve |
| david | george |
| eve | alice |
| eve | bob |
| eve | charlie |
| fred | alice |
| fred | eve |
| george | george |
Took 0ms{\n "relation": "OK",\n "time_taken": 0\n}"
+ },
+ "metadata": {}
+ }
+ ]
+ },
+ {
+ "cell_type": "code",
+ "source": "?[a, b] := :triangles[a, b]",
+ "metadata": {
+ "trusted": true
+ },
+ "execution_count": 64,
+ "outputs": [
+ {
+ "execution_count": 64,
+ "output_type": "execute_result",
+ "data": {
+ "text/html": "| a | b |
| alice | eve |
| bob | alice |
| charlie | eve |
| david | george |
| eve | bob |
| fred | alice |
| fred | eve |
| george | george |
Took 0ms{\n "relation": "OK",\n "time_taken": 0\n}"
+ },
+ "metadata": {}
+ }
+ ]
+ },
+ {
+ "cell_type": "code",
+ "source": "?[a, b] := :triangles[a, b]",
+ "metadata": {
+ "trusted": true
+ },
+ "execution_count": 66,
+ "outputs": [
+ {
+ "execution_count": 66,
+ "output_type": "execute_result",
+ "data": {
+ "text/html": ""
+ },
+ "metadata": {}
+ }
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "source": "Only the `rederive`ed tuples remain.",
+ "metadata": {}
+ },
+ {
+ "cell_type": "markdown",
+ "source": "You can see what stored relations you currently have in your database by running the following _system directive_:",
+ "metadata": {}
+ },
+ {
+ "cell_type": "code",
+ "source": ":db relations",
+ "metadata": {
+ "trusted": true
+ },
+ "execution_count": 67,
+ "outputs": [
+ {
+ "execution_count": 67,
+ "output_type": "execute_result",
+ "data": {
+ "text/html": "| name | arity |
| code_lat_lon | 3 |
| flies_to | 3 |
| flies_to_code | 3 |
| triangles | 2 |
Took 0ms{\n "status": "OK",\n "time_taken": 0\n}"
+ },
+ "metadata": {}
+ }
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "source": "Since we do not have any queries to run when nuking relations, we use a system directive instead of a query directive. Now you can no longer query the triangles:",
+ "metadata": {}
+ },
+ {
+ "cell_type": "code",
+ "source": "?[a, b] := :triangles[a, b]",
+ "metadata": {
+ "trusted": true
+ },
+ "execution_count": 69,
+ "outputs": [
+ {
+ "execution_count": 69,
+ "output_type": "execute_result",
+ "data": {
+ "text/html": "query::relation_not_found\n\n × Cannot find requested stored relation 'triangles'\n ╭────\n 1 │ ?[a, b] := :triangles[a, b]\n · ──────────\n ╰────\n
"
+ },
+ "metadata": {}
+ }
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "source": "This completes all the operations on stored relations: `create`, `put`, `retract`, `rederive`. The syntax for `remove` is different from the rest for technical reasons.\n\nAll these operations are _atomic_, meaning that for all the tuples they affect, either all are affected at the same time, or the operation completely fails. There is no in-between, corrupted state.",
+ "metadata": {}
+ },
+ {
+ "cell_type": "markdown",
+ "source": "## A schema for data",
+ "metadata": {}
+ },
+ {
+ "cell_type": "markdown",
+ "source": "The stored relation operations introduced above are simple, fast, and very raw. They can be used in exactly the same way as rules defined inline with the query. The way you use them is also not very different than in a traditional SQL database.\n\nStored relations are suitable for data that has a well-defined structure at the onset, and which is loaded and updated in bulk. For example, you may have obtained from domain experts an [ontology](https://www.wikiwand.com/en/Ontology_\\(information_science\\)) in the form of a network of metadata. The ontology comes in nice tables with clear, detailed documentation. You store this ontology as a group of stored relations, and use them to extract insights from your business data. The ontology is updated periodically, and when an update comes you just use the `rederive` operation to replace the old version. Very simple and efficient.",
+ "metadata": {}
+ },
+ {
+ "cell_type": "markdown",
+ "source": "But your _business_ data is mostly likely not as simple as that. At this age of BigDataⒸ, you must have one billion active users on your platforms carrying out all sorts of activities, concurrently of course. You don't want these activities to step on each other. You don't want to store the wrong thing into your user's accounts. You _especially_ don't want any money in transit to disappear in midair. To make things worse, hundreds of new activities pop up each day. \n\nYou don't want to store any of those in a stored relation. With a traditional RDBMS, [data migrations](https://en.wikipedia.org/wiki/Data_migration) would have already killed you. And with Cozo, stored relations don't even try to support schema change (in fact, the only 'schema' for a stored relation is its arity).\n\nSo let's step back a bit and recap what we want in this case:\n\n* high concurrency;\n* fine-grained transactions;\n* checks for data integrity;\n* ability to rapidly adapt to changing data shapes.\n\nBut at what cost? We have to give up something, right? Here are the prices we are willing to pay in this case:\n\n* we restrict most transactions to _local changes_: i.e. they only touch on a tiny fraction of the data;\n* we can tolerate levels of indirections.",
+ "metadata": {}
+ },
+ {
+ "cell_type": "markdown",
+ "source": "After we've paid our price we got our solution. It is a very old solution actually: the [triple store](https://en.wikipedia.org/wiki/Triplestore).",
+ "metadata": {}
+ },
+ {
+ "cell_type": "markdown",
+ "source": "The idea is very simple. a _triple_ is a sentence consisting of a subject, a verb, and an object. In the Cozo flavour, the subject is always an opaque identity, such as _entity42_. The following are examples of triples in this sense:\n\n* _entity42_ has first name `'Alice'`.\n* _entity42_ has last name `'Liddell'`.\n* _entity42_ loves _entity81_.\n* _entity81_ is aged `20` years old.",
+ "metadata": {}
+ },
+ {
+ "cell_type": "markdown",
+ "source": "We put schema into triples by schematize the verbs. We see that in our case, the schema for first name and last name should have type strings, the schema for age should have type integers, and the schema for the \"loves\" relationship should be other entities. Here the types refer to the objects in the triple, since the subject is always an entity.",
+ "metadata": {}
+ },
+ {
+ "cell_type": "markdown",
+ "source": "So let's finally put this into code:",
+ "metadata": {}
+ },
+ {
+ "cell_type": "code",
+ "source": ":schema\n\nput person {\n first_name: string index,\n last_name: string index,\n loves: ref many,\n age: int\n}",
+ "metadata": {
+ "trusted": true
+ },
+ "execution_count": 70,
+ "outputs": [
+ {
+ "execution_count": 70,
+ "output_type": "execute_result",
+ "data": {
+ "text/html": "{\n "results": [\n [\n 10000020,\n "+"\n ],\n [\n 10000021,\n "+"\n ],\n [\n 10000022,\n "+"\n ],\n [\n 10000023,\n "+"\n ]\n ],\n "time_taken": 0,\n "tx_id": 10011\n}"
+ },
+ "metadata": {}
+ }
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "source": "Let's explain. The `:schema` at the top indicates that we want to manage the schema instead of run normal queries. We then `put` a _group_ of related schema. Now even though they are declared together similarly to a table definition in SQL, we need to stress that this actually defines four separate, independent attributes named `person.first_name`, `person.last_name`, `person.loves`, `person.age`. An entity can have whatever attributes associated with it, even those with different prefixes.",
+ "metadata": {}
+ },
+ {
+ "cell_type": "markdown",
+ "source": "The allowed types for attributes are:\n\n* `ref`\n* `bool`\n* `int`\n* `float`\n* `string`\n* `bytes`\n* `list`\n\nThe list type is heterogeneous in its elements. There is no concept of a nullable type and you can't put `null` into values of triples (other than wrapping them in lists first). To indicate missing values, you simply omit the attribute.\n\nThe `ref` type has the special meaning of refering to other entities.\n\nAfter the type comes one or more _modifiers_. The `many` modifier indicates that `loves` is a to-many relationship. If we omit it, any person can love at most one other person, which is not very realistic.\n\nThe modifier `index` indicates that we want values of this attribute to be _indexed_. Only indexed attributes support efficient value lookups and range scans. `ref` types are always implicitly indexed since the database wants to be able to traverse the graph in both directions.",
+ "metadata": {}
+ },
+ {
+ "cell_type": "markdown",
+ "source": "Instead of `index`, we can mark attributes with the modifier `unique`, indicating there cannot be two entities with the same value for the attribute. The value then acts as an _unique identifier_ for the entity, which is convenient in certain circumstances since the entity ID is assigned by the database automatically and you cannot choose it. So let's add an explicit `person.id` attribute, this time using the non-grouped syntax:",
+ "metadata": {}
+ },
+ {
+ "cell_type": "code",
+ "source": ":schema\n\nput person.id: string unique;",
+ "metadata": {
+ "trusted": true
+ },
+ "execution_count": 72,
+ "outputs": [
+ {
+ "execution_count": 72,
+ "output_type": "execute_result",
+ "data": {
+ "text/html": "{\n "results": [\n [\n 10000024,\n "+"\n ]\n ],\n "time_taken": 0,\n "tx_id": 10012\n}"
+ },
+ "metadata": {}
+ }
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "source": "We can see what schema are there in the database now by running a system directive:",
+ "metadata": {}
+ },
+ {
+ "cell_type": "code",
+ "source": ":db schema",
+ "metadata": {
+ "trusted": true
+ },
+ "execution_count": 73,
+ "outputs": [
+ {
+ "execution_count": 73,
+ "output_type": "execute_result",
+ "data": {
+ "text/html": "| id | name | type | cardinality | index | history |
| 10000001 | country.code | string | one | unique | false |
| 10000002 | country.desc | string | one | none | false |
| 10000003 | continent.code | string | one | unique | false |
| 10000004 | continent.desc | string | one | none | false |
| 10000005 | airport.iata | string | one | unique | false |
| 10000006 | airport.icao | string | one | index | false |
| 10000007 | airport.city | string | one | index | false |
| 10000008 | airport.desc | string | one | none | false |
| 10000009 | airport.region | string | one | index | false |
| 10000010 | airport.country | ref | one | none | false |
| 10000011 | airport.runways | int | one | none | false |
| 10000012 | airport.longest | int | one | none | false |
| 10000013 | airport.altitude | int | one | none | false |
| 10000014 | airport.lat | float | one | none | false |
| 10000015 | airport.lon | float | one | none | false |
| 10000016 | route.src | ref | one | none | false |
| 10000017 | route.dst | ref | one | none | false |
| 10000018 | route.distance | int | one | none | false |
| 10000019 | geo.contains | ref | many | none | false |
| 10000020 | person.first_name | string | one | index | false |
| 10000021 | person.last_name | string | one | index | false |
| 10000022 | person.loves | ref | many | none | false |
| 10000023 | person.age | int | one | none | false |
| 10000024 | person | string | one | unique | false |
Took 0ms