-spec authenticate(surreal_pid(), Token :: iodata()) -> surreal_result:result().

Authenticates the current connection with a JWT token.

1> Token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc...".
   % "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc..."
2> surreal:authenticate(Pid, Token).
   % {ok,null}

-spec close(surreal_pid()) -> ok.

Closes the persistent connection to the database.

1> surreal:close(Pid).
   % ok

-spec create(surreal_pid(), Thing :: surreal_entity:thing(), Data :: map() | null) ->
          surreal_result:result().

Creates a record in the database.

1> User = #{<<"name">> => <<"meppu">>, <<"identify">> => <<"cat">>}.
   % #{<<"identify">> => <<"cat">>,<<"name">> => <<"meppu">>}
2> {ok, Created} = surreal:create(Pid, {"users", "meppu"}, User).
   % {ok,#{<<"id">> => <<"users:meppu">>,<<"identify">> => <<"cat">>,
   %       <<"name">> => <<"meppu">>}}
3> {ok, Created2} = surreal:create(Pid, "users", User).
   % {ok,[#{<<"id">> => <<"users:pmqsma4cqhescl1wlsi1">>,
   %        <<"identify">> => <<"cat">>,<<"name">> => <<"meppu">>}]}

-spec delete(surreal_pid(), Thing :: surreal_entity:thing()) -> surreal_result:result().

Deletes all records in a table, or a specific record, from the database.

1> {ok, Deleted} = surreal:merge(Pid, {"users", "meppu"}).
   % {ok,#{<<"id">> => <<"users:meppu">>,<<"identify">> => <<"human">>,
   %       <<"name">> => <<"meppu">>,<<"score">> => 10}}

-spec insert(surreal_pid(), Thing, Data) -> surreal_result:result()
          when Thing :: surreal_entity:thing(), Data :: map() | [map()].

Inserts one or multiple records in the database.

1> AuthorisedUsers = [#{<<"user">> => <<"A">>}, #{<<"user">> => <<"B">>}].
   % [#{<<"user">> => <<"A">>},#{<<"user">> => <<"B">>}]
2> {ok, Created} = surreal:insert(Pid, "authorised", AuthorisedUsers).
   % {ok,[#{<<"id">> => <<"authorised:3n4mn5wsq823i7pgv9un">>,
   %        <<"user">> => <<"A">>},
   %      #{<<"id">> => <<"authorised:raedq65doxhpuc6t3meo">>,
   %        <<"user">> => <<"B">>}]}

-spec invalidate(surreal_pid()) -> surreal_result:result().

Invalidates the authentication for the current connection.

1> surreal:invalidate(Pid).
   % {ok,null}

-spec merge(surreal_pid(), Thing, Data) -> surreal_result:result()
         when Thing :: surreal_entity:thing(), Data :: map() | null.

Modifies all records in a table, or a specific record, in the database.

This function merges the current document/record data with the specified data.

1> MergeData = #{<<"score">> => 10}.
   % #{<<"score">> => 10}
2> {ok, Updated} = surreal:merge(Pid, {"users", "meppu"}, MergeData).
   % {ok,#{<<"id">> => <<"users:meppu">>,<<"identify">> => <<"human">>,
   %       <<"name">> => <<"meppu">>,<<"score">> => 10}}

-spec patch(surreal_pid(), Thing, JSONPatch) -> surreal_result:result()
         when Thing :: surreal_entity:thing(), JSONPatch :: [surreal_patch:patch()] | null.

Applies JSON Patch changes to all records, or a specific record, in the database.

This function patches the current document/record data with the specified JSON Patch data.

1> Patches = [{replace, "/name", <<"tuhana">>}, {remove, "/score"}].
   % [{replace,"/name",<<"tuhana">>},{remove,"/score"}]
2> surreal:patch(database, {"users", "meppu"}, Patches).
   % {ok,[#{<<"op">> => <<"remove">>,<<"path">> => <<"/score">>,
   %        <<"value">> => null},
   %      #{<<"op">> => <<"change">>,<<"path">> => <<"/name">>,
   %        <<"value">> => <<"@ -1,5 +1,6 @\n-meppu\n+tuhana\n">>}]}

-spec ping(surreal_pid()) -> surreal_result:result().

Ping SurrealDB instance.

1> surreal:ping(Pid).
   % {ok,null}

-spec query(surreal_pid(), Query :: iodata()) -> surreal_result:result().

Executes a set of SurrealQL statements against the database.

1> [{ok, Result}] = surreal:query(Pid, "SELECT * FROM authorised").
   % {ok,[#{<<"id">> => <<"authorised:3n4mn5wsq823i7pgv9un">>,
   %        <<"user">> => <<"A">>},
   %      #{<<"id">> => <<"authorised:raedq65doxhpuc6t3meo">>,
   %        <<"user">> => <<"B">>}]}

-spec query(surreal_pid(), Query :: iodata(), Variables :: map()) -> surreal_result:result().

Executes a set of SurrealQL statements against the database with variables.

This function is similar to query/2, but allows you to provide a map of variables that can be used in the query.

This can be useful for dynamic queries where you need to parametrise certain parts of the query.

1> [{ok, Result}] = surreal:query(Pid, "SELECT * FROM authorised WHERE user = $user", #{<<"user">> => <<"A">>}).
   % [{ok,[#{<<"id">> => <<"authorised:3n4mn5wsq823i7pgv9un">>,
   %        <<"user">> => <<"A">>}]}]

-spec select(surreal_pid(), Thing :: surreal_entity:thing()) -> surreal_result:result().

Retrieves all records in a table or a specific record.

1> {ok, Result} = surreal:select(Pid, "authorised").
   % {ok,[#{<<"id">> => <<"authorised:3n4mn5wsq823i7pgv9un">>,
   %        <<"user">> => <<"A">>},
   %      #{<<"id">> => <<"authorised:raedq65doxhpuc6t3meo">>,
   %        <<"user">> => <<"B">>}]}
2> {ok, Result2} = surreal:select(Pid, {"users", "meppu"}).
   % {ok,#{<<"id">> => <<"users:meppu">>,<<"identify">> => <<"cat">>,
   %       <<"name">> => <<"meppu">>}}

-spec set(surreal_pid(), Variable :: iodata(), Value :: term()) -> surreal_result:result().

Creates a variable that can be used throughout the database session.

1> surreal:set(Pid, "PI", 3.14).
   % {ok,null}

-spec signin(surreal_pid(), Vars :: map()) -> surreal_result:result().

Signs in to a root, namespace, database or scope user.

For more information about Vars, view SurrealDB documentation and the JavaScript SDK.

1> Vars = #{<<"DB">> => <<"test">>,<<"NS">> => <<"test">>,
1>  <<"SC">> => <<"user">>,
1>  <<"email">> => <<"info@surrealdb.com">>,
1>  <<"pass">> => <<"123456">>}.
   % #{...}
2> surreal:signin(Pid, Vars).
   % {ok, <<"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc"...>>}

-spec signin(surreal_pid(), Username :: iodata(), Password :: iodata()) -> surreal_result:result().

Signs in to the database with a username and password.

1> surreal:signin(Pid, "root", "root").
   % {ok,null}

-spec signup(surreal_pid(), Vars :: map()) -> surreal_result:result().

Signs up a user to a specific authentication scope.

For more information about Vars, view SurrealDB documentation and the JavaScript SDK.

1> Vars = #{<<"DB">> => <<"test">>,<<"NS">> => <<"test">>,
1>  <<"SC">> => <<"user">>,
1>  <<"email">> => <<"info@surrealdb.com">>,
1>  <<"pass">> => <<"123456">>}.
   % #{...}
2> surreal:signup(Pid, Vars).
   % {ok, <<"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc"...>>}

-spec start_link(Uri :: nonempty_string(), ConnName :: atom()) -> gen_server:start_ret().

Establishes a connection to a local or remote database endpoint.

- Uri must be a valid SurrealDB URI. For more information, visit surreal_config.

- ConnName allows you to set a name for the connection, so you can use the given name instead of pid while using SurrealDB.

1> Uri = "surrealdb://root:root@localhost:8000/surrealdb/docs".
   % "surrealdb://root:root@localhost:8000/surrealdb/docs"
2> {ok, Pid} = surreal:start_link(Uri, database).
   % {ok,<0.359.0>}

-spec start_link(Uri, ConnName, Opts) -> gen_server:start_ret()
              when Uri :: nonempty_string(), ConnName :: atom(), Opts :: surreal_opts().

Connects to a local or remote database endpoint with additional options.

Essentially the same as surreal:start_link/2 but with an extra argument:

- Opts allows you to provide custom options.

1> Uri = "surrealdb://root:root@localhost:8000/surrealdb/docs".
   % "surrealdb://root:root@localhost:8000/surrealdb/docs"
2> {ok, Pid} = surreal:start_link(Uri, database, #{use => false}).
   % {ok,<0.359.0>}

-spec unset(surreal_pid(), Variable :: iodata()) -> surreal_result:result().

Removes a variable from the current socket connection.

1> surreal:unset(Pid, "PI").
   % {ok,null}

-spec update(surreal_pid(), Thing, NewData) -> surreal_result:result()
          when Thing :: surreal_entity:thing(), NewData :: map() | null.

Updates all records in a table, or a specific record, in the database.

This function replaces the current document/record data with the specified data.

1> NewData = #{<<"name">> => <<"meppu">>, <<"identify">> => <<"human">>}.
   % #{<<"identify">> => <<"human">>,<<"name">> => <<"meppu">>}
2> {ok, Updated} = surreal:update(Pid, {"users", "meppu"}, NewData).
   % {ok,#{<<"id">> => <<"users:meppu">>,<<"identify">> => <<"human">>,
   %       <<"name">> => <<"meppu">>}}

-spec use(surreal_pid(), Namespace :: iodata(), Database :: iodata()) -> surreal_result:result().

Switches to a specific namespace and database.

1> surreal:use(Pid, "test", "test").
   % {ok,null}