View Source cozo (cozo v0.1.0)

Main interface to CozoDB Erlang NIF cozo_nif module.

Summary

Functions

Backup a database to a file.

Close an opened database.

Unstable interface. Instructs Cozo to run a compaction job.

Unstable interface. Create a stored relation with the given name and spec. No stored relation with the same name can exist beforehand.

Unstable interface. Describe the stored relation and store it in the metadata.

Unstable interface. Ensure that rows specified by the output relation and spec do not exist in the database and that no other process has written to these rows when the enclosing transaction commits.

Unstable interface. Ensure that rows specified by the output relation and spec exist in the database, and that no other process has written to these rows when the enclosing transaction commits. Useful for ensuring read-write consistency.

Unstable interface. Explain a query.

Export database relationships from json as map.

Unstable interface. Display running queries and their id.

Unstable interface. Display triggers.

Import a database backup from json like object as map.

Import relations as json.

returns the default json decoder (thoas)
returns the default json encoder (thoas)

Unstable interface. Kill a running query specified by id.

Unstable interface. List all columns for the stored relation.

Unstable interface. List all indices for the stored relation.

Unstable interface. Returns the list of relations.

Open the database with mem engine, with random path and default options.

Open a new database with custom engine and random path. The random path is set to /tmp` by default and the filename is prefixed by `cozodb_.

Open a database with a custom engine and path.

Open a new databse with custom path and options.

Unstable interface. Put rows from the resulting relation into the named stored relation.

Unstable interface. Remove a stored relation.

Unstable interface. Remove a stored relations.

Unstable interface. Remove rows from the named stored relation.

Unstable interface. Similar to :create, except that if the named stored relation exists beforehand, it is completely replaced.

Restore a database based from a backup path.

run a query using cozoscript on defined db and custom query. No parameters are passed and immutability is set to true.

run a query using cozoscript on defined db with custom params. Immutability is set to true.

Run a query using cozoscript.

Unstable interface.

Unstable interface. Update rows in the named stored relation.

Types

-type db_engine() :: mem | sqlite | rocksdb.
-type db_id() :: 0 | pos_integer().
-type db_options() :: map().
-type db_parent() :: pid().
-type db_path() :: string().
-type db_query() :: string() | binary() | [string(), ...].
-type query_mutable() :: boolean().
-type query_params() :: map().
-type query_return() :: {ok, string()} | {error, any()}.

Functions

-spec backup(Db, OutPath) -> Return
          when Db :: pos_integer(), OutPath :: string(), Return :: {ok, map()} | {error, term()}.

Backup a database to a file.

see https://docs.cozodb.org/en/latest/nonscript.html#API.backup

Examples

  {ok, _} = cozo:backup(Db, "/tmp/backup.db").
-spec close(Db) -> Return when Db :: db_id(), Return :: ok | {error, term()}.

Close an opened database.

Examples

  ok = cozo:close(0).
-spec compact(Db) -> Return when Db :: db_id(), Return :: query_return().

Unstable interface. Instructs Cozo to run a compaction job.

Examples

  {ok, _} = cozo:compact(Db).
Link to this function

create_filepath(Path, Prefix, Length)

View Source
-spec create_filepath(Path, Prefix, Length) -> Return
                   when
                       Path :: string(),
                       Prefix :: string(),
                       Length :: pos_integer(),
                       Return :: string().
Link to this function

create_relation(Db, Name, Spec)

View Source
-spec create_relation(Db, Name, Spec) -> Return
                   when
                       Db :: db_id(),
                       Name :: string() | atom(),
                       Spec :: string() | atom() | [string(), ...] | [atom(), ...],
                       Return :: query_return().

Unstable interface. Create a stored relation with the given name and spec. No stored relation with the same name can exist beforehand.

Examples

  {ok, _} = cozo:create_relation(Db, "stored1", "c1").
  % :create stored1 {c1}
 
  {ok, _} = cozo:create_relation(Db, stored2, c1).
  % :create stored2 {c1}
 
  {ok, _} = cozo:create_relation(Db, stored3, ["c1","c2","c3"]).
  % :create stored3 {c1,c2,c3}
 
  {ok, _} = cozo:create_relation(Db, stored4, [c1,c2,c3]).
  % :create stored4 {c1,c2,c3}
Link to this function

describe(Db, Name, Description)

View Source
-spec describe(Db, Name, Description) -> Return
            when
                Db :: db_id(), Name :: string(), Description :: string(), Return :: query_return().

Unstable interface. Describe the stored relation and store it in the metadata.

Examples

  {ok, _} = cozo:describe(Db, Relation).

See also: run/4.

Link to this function

ensure_not_row(Db, Name, Spec)

View Source
-spec ensure_not_row(Db, Name, Spec) -> Return
                  when Db :: db_id(), Name :: string(), Spec :: string(), Return :: query_return().

Unstable interface. Ensure that rows specified by the output relation and spec do not exist in the database and that no other process has written to these rows when the enclosing transaction commits.

Examples

  {ok, _} = cozo:ensure_not_row(Db, Name, Spec).
Link to this function

ensure_row(Db, Name, Spec)

View Source
-spec ensure_row(Db, Name, Spec) -> Return
              when Db :: db_id(), Name :: string(), Spec :: string(), Return :: query_return().

Unstable interface. Ensure that rows specified by the output relation and spec exist in the database, and that no other process has written to these rows when the enclosing transaction commits. Useful for ensuring read-write consistency.

Examples

  {ok, _} = cozo:ensure_row(Db, Name, Spec).
-spec explain(Db, Query) -> Return when Db :: db_id(), Query :: string(), Return :: query_return().

Unstable interface. Explain a query.

see https://docs.cozodb.org/en/latest/sysops.html#explain

Examples

  Query = "?[] <- [['hello', 'world', 'Cozo!']]",
  {ok, _} = (Db, Query).
Link to this function

export_relations(Db, Json)

View Source
-spec export_relations(Db, Json) -> Return
                    when
                        Db :: pos_integer(),
                        Json :: map() | list(),
                        Return :: {ok, map()} | {error, term()}.

Export database relationships from json as map.

see https://docs.cozodb.org/en/latest/nonscript.html#API.export_relations

Examples

  {ok, _} = cozo:export_relations(Db, #{}).
-spec get_running_queries(Db) -> Return when Db :: db_id(), Return :: query_return().

Unstable interface. Display running queries and their id.

Examples

  {ok, _} = cozo:get_running_queries(Db).
-spec get_triggers(Db, Name) -> Return when Db :: db_id(), Name :: string(), Return :: query_return().

Unstable interface. Display triggers.

Examples

  {ok, _} = cozo:get_triggers(Db, Trigger).
-spec import_backup(Db, Json) -> Return
                 when Db :: pos_integer(), Json :: map(), Return :: {ok, map()} | {error, term()}.

Import a database backup from json like object as map.

see https://docs.cozodb.org/en/latest/nonscript.html#API.import_from_backup

Examples

  {ok, _} = cozo:import_backup(Db, #{}).
Link to this function

import_relations(Db, Json)

View Source
-spec import_relations(Db, Json) -> Return
                    when
                        Db :: pos_integer(),
                        Json :: map() | list(),
                        Return :: {ok, map()} | {error, term()}.

Import relations as json.

see https://docs.cozodb.org/en/latest/nonscript.html#API.import_relations

Examples

  {ok, _} = cozo:import_relations(Db, #{}).
-spec json_decoder() -> atom().
returns the default json decoder (thoas)
-spec json_encoder() -> atom().
returns the default json encoder (thoas)
-spec kill(Db, Id) -> Return when Db :: db_id(), Id :: string(), Return :: query_return().

Unstable interface. Kill a running query specified by id.

Examples

  {ok, _} = cozo:kill(Db, Id).
-spec list_columns(Db, Name) -> Return when Db :: db_id(), Name :: string(), Return :: query_return().

Unstable interface. List all columns for the stored relation.

Examples

  {ok, _} = cozo:list_columns(Db, Column).
-spec list_indices(Db, Name) -> Return when Db :: db_id(), Name :: string(), Return :: query_return().

Unstable interface. List all indices for the stored relation.

Examples

  {ok, _} = cozo:list_indices(Db, Indice).
-spec list_relations(Db) -> Return when Db :: db_id(), Return :: query_return().

Unstable interface. Returns the list of relations.

Examples

  {ok, _} = cozo:list_relations(Db).
-spec open() -> Return when Return :: {ok, {db_id(), #cozo{}}} | {error, term()}.

Open the database with mem engine, with random path and default options.

Examples

  rr(cozo)
  {ok, {0, State}} = cozo:open().
  #cozo{ id = 0
       , db_engine = mem
       , db_path = "/tmp/cozodb_Lq4yHM0RbGxbIwlyPBcNPyqPEj7O4msJ"
       , db_options = #{}
       , db_parent = <0.161>
  } = State.

See also: open/1, open/2, open/3.

-spec open(Engine) -> Return
        when Engine :: db_engine(), Return :: {ok, {db_id(), #cozo{}}} | {error, term()}.

Open a new database with custom engine and random path. The random path is set to /tmp` by default and the filename is prefixed by `cozodb_.

Examples

  rr(cozo).
  {ok {0, #cozo{ db_path = Path }}} = open(mem).
  "/tmp/cozodb_aPmybeM4XTudF5qJPnG5hJusV2Evq5au" = Path.
 
  {ok, {1, #cozo{ db_path = SqlitePath }}} = open(sqlite).
  "/tmp/cozodb_TDE4dQKtiXHIUjWyNEaAo1f7LAxrYk4O" = SqlitePath.
 
  {ok, {1, #cozo{ db_path = RocksDbPath }}} = open(rocksdb).
  "/tmp/cozodb_S8jAUccVnge0cKfci9FYvjrK1O6fAO1S" = RocksDbPath

See also: open/2, open/3.

-spec open(Engine, Path) -> Return
        when
            Engine :: db_engine(),
            Path :: db_path(),
            Return :: {ok, {db_id(), #cozo{}}} | {error, term()}.

Open a database with a custom engine and path.

Examples

  {ok, {0, State}} = cozo:open(sqlite, "/tmp/database.db").

See also: open/3.

Link to this function

open(Engine, Path, DbOptions)

View Source
-spec open(Engine, Path, DbOptions) -> Return
        when
            Engine :: db_engine(),
            Path :: db_path(),
            DbOptions :: db_options(),
            Return :: {ok, {db_id(), #cozo{}}} | {error, term()}.

Open a new databse with custom path and options.

Examples

  {ok, {0, State}} = cozo:open(rocksdb, "/tmp/rocks.db", #{}).
-spec put_row(Db, Name, Spec) -> Return
           when Db :: db_id(), Name :: string(), Spec :: string(), Return :: query_return().

Unstable interface. Put rows from the resulting relation into the named stored relation.

Examples

  {ok, _} = cozo:put_row(Db, Name, Spec).
Link to this function

remove_relation(Db, Name)

View Source
-spec remove_relation(Db, Name) -> Return when Db :: db_id(), Name :: string(), Return :: query_return().

Unstable interface. Remove a stored relation.

Examples

  {ok, _} = cozo:remove_relations(Db, Relation).

See also: run/4.

Link to this function

remove_relations(Db, Names)

View Source
-spec remove_relations(Db, Names) -> Return
                    when Db :: db_id(), Names :: [string(), ...], Return :: query_return().

Unstable interface. Remove a stored relations.

Examples

  {ok, _} = cozo:remove_relations(Db, [R1, R2, R3]).
Link to this function

remove_row(Db, Name, Spec)

View Source
-spec remove_row(Db, Name, Spec) -> Return
              when Db :: db_id(), Name :: string(), Spec :: string(), Return :: query_return().

Unstable interface. Remove rows from the named stored relation.

Examples

  {ok, _} = cozo:remove_row(Db, Name, Spec).
Link to this function

replace_relation(Db, Name, Spec)

View Source
-spec replace_relation(Db, Name, Spec) -> Return
                    when
                        Db :: db_id(),
                        Name :: string(),
                        Spec :: string(),
                        Return :: query_return().

Unstable interface. Similar to :create, except that if the named stored relation exists beforehand, it is completely replaced.

Examples

  {ok, _} = cozo:replace_relation(Db, Name, Spec).
-spec restore(Db, InPath) -> Return
           when Db :: pos_integer(), InPath :: string(), Return :: {ok, map()} | {error, term()}.

Restore a database based from a backup path.

see https://docs.cozodb.org/en/latest/nonscript.html#API.restore

Examples

  {ok, _} = cozo:restore(Db, "/tmp/backup.db").
-spec run(Db, Query) -> Return when Db :: db_id(), Query :: db_query(), Return :: query_return().

run a query using cozoscript on defined db and custom query. No parameters are passed and immutability is set to true.

Examples

  {ok, #{ <<"headers">> => [<<"_0">>,<<"_1">>,<<"_2">>]
          <<"next">> => null,
          <<"ok">> => true,
          <<"rows">> => [[1,2,3]],
          <<"took">> => 2.40886e-4}
  } = cozo:run(0, "?[] <- [[1, 2, 3]]").
-spec run(Db, Query, Params) -> Return
       when Db :: db_id(), Query :: db_query(), Params :: query_params(), Return :: query_return().

run a query using cozoscript on defined db with custom params. Immutability is set to true.

Examples

  {ok, #{ <<"headers">> => [<<"_0">>,<<"_1">>,<<"_2">>]
          <<"next">> => null,
          <<"ok">> => true,
          <<"rows">> => [[1,2,3]],
          <<"took">> => 2.40886e-4}
  } = cozo:run(0, "?[] <- [[1, 2, 3]]", #{}).
Link to this function

run(Db, Query, Params, Mutable)

View Source
-spec run(Db, Query, Params, Mutable) -> Return
       when
           Db :: db_id(),
           Query :: db_query(),
           Params :: query_params(),
           Mutable :: query_mutable(),
           Return :: query_return().

Run a query using cozoscript.

Examples

  {ok, #{ <<"headers">> => [<<"_0">>,<<"_1">>,<<"_2">>]
          <<"next">> => null,
          <<"ok">> => true,
          <<"rows">> => [[1,2,3]],
          <<"took">> => 2.40886e-4}
  } = cozo:run(0, "?[] <- [[1, 2, 3]]", #{ limit => 10 }, falsex).
Link to this function

set_access_level(Db, Level, Name)

View Source
-spec set_access_level(Db, Level, Name) -> Return
                    when
                        Db :: db_id(),
                        Level :: string(),
                        Name :: string(),
                        Return :: query_return().

Unstable interface.

Examples

  {ok, _} = cozo:set_access_level(Db, Level, Name).
Link to this function

set_access_levels(Db, Level, Names)

View Source
-spec set_access_levels(Db, Level, Names) -> Return
                     when
                         Db :: db_id(),
                         Level :: string(),
                         Names :: [string(), ...],
                         Return :: query_return().

Unstable interface.

Examples

  {ok, _} = cozo:se_access_levelss(Db, Level, [N1, N2, N3]).
Link to this function

update_row(Db, Name, Spec)

View Source
-spec update_row(Db, Name, Spec) -> Return
              when Db :: db_id(), Name :: string(), Spec :: string(), Return :: query_return().

Unstable interface. Update rows in the named stored relation.

Examples

  {ok, _} = cozo:update_row(Db, Name, Spec).