View Source Cosmox.Document (Cosmox v0.1.0)

The API to manage the documents inside a container.

Link to this section Summary

Functions

Creates a document in the given container in the given database. The function accept both a struct and a map, but either must have a pk key to represent the partition key in which the document will be inserted. The partition key is an important concept in Cosmos, please refer to Cosmos documentation for more information.

Deletes the document from the given database/container.

List all the documents on the given db/container/partition key. By giving the struct in input, the library will try deserialize the list to that.

List all the documents on the given db/container/partition key. By giving the struct in input, the library will try deserialize the list item to that.

Patches some fields of an existing document, provided the key of the property, and its value.

Applies the query to the specified database/container set passed in input, with the given parameters. This function will apply the query only on a particular partition key, that will have to be defined in the query. This function will not apply the partition key automatically: the partition key will have to be specified manually in the query by adding a filter over the pk field of the collection, and by subsequently adding the related parameter in the parameter list.

Applies the query to the specified database/container set passed in input, with the given parameters. This query will span data across partitions.

Replaces the content of the document identified by the id and the partition key given in input.

Link to this section Types

@type empty_response() ::
  :ok | {:error | Cosmox.Response.ErrorMessage.t()} | {:error | any()}
@type response(term) ::
  {:ok, term | map()}
  | {:error | Cosmox.Response.ErrorMessage.t()}
  | {:error | any()}

Link to this section Functions

Link to this function

create_document(database_id, container_id, item)

View Source
@spec create_document(
  database_id :: binary(),
  container_id :: binary(),
  item :: term() | map()
) :: response(term())

Creates a document in the given container in the given database. The function accept both a struct and a map, but either must have a pk key to represent the partition key in which the document will be inserted. The partition key is an important concept in Cosmos, please refer to Cosmos documentation for more information.

examples

Examples

iex> person = %Cosmox.Structs.Tests.Person{ ...> id: "1", ...> pk: "pk1", ...> name: "Some Name", ...> surname: "Some Surname", ...> age: 55 ...> } %Cosmox.Structs.Tests.Person{

age: 55,
id: "1",
name: "Some Name",
pk: "pk1",
surname: "Some Surname"

} iex> Cosmox.Document.create_document("test_db", "test_container", person) {:ok, %Cosmox.Structs.DocumentInfo{

_attachments: "attachments/",
_etag: ""d1028ad3-0000-0c00-0000-630de4900000"",
_rid: "lJweAJDf4xcBAAAAAAAAAA==",
_self: "dbs/lJweAA==/colls/lJweAJDf4xc=/docs/lJweAJDf4xcBAAAAAAAAAA==/",
_ts: 1661854864,
pk: "pk1"

}}

iex> map = %{ ...> "id" => "2", ...> "pk" => "pk1", ...> "name" => "Some Other Name", ...> "surname" => "Some Other Surname", ...> "age" => 45 ...> } %{

"age" => 45,
"id" => "2",
"name" => "Some Other Name",
"pk" => "pk1",
"surname" => "Some Other Surname"

} iex> Cosmox.Document.create_document("test_db", "test_container", map) {:ok, %Cosmox.Structs.DocumentInfo{

_attachments: "attachments/",
_etag: ""d302b4a3-0000-0c00-0000-630de9900000"",
_rid: "lJweAJDf4xcCAAAAAAAAAA==",
_self: "dbs/lJweAA==/colls/lJweAJDf4xc=/docs/lJweAJDf4xcCAAAAAAAAAA==/",
_ts: 1661856144,
pk: "pk1"

}}

Link to this function

delete_document(database_id, container_id, id, partition_key)

View Source
@spec delete_document(
  database_id :: binary(),
  container_id :: binary(),
  id :: binary(),
  partition_key :: binary()
) :: empty_response()

Deletes the document from the given database/container.

example

Example

iex> person = %Cosmox.Structs.Tests.Person{ ...> id: "1", ...> pk: "pk1", ...> name: "Some Name", ...> surname: "Some Surname", ...> age: 55 ...> } %Cosmox.Structs.Tests.Person{

age: 55,
id: "1",
name: "Some Name",
pk: "pk1",
surname: "Some Surname"

} iex> Cosmox.Document.create_document("test_db", "test_container", person) {:ok, %Cosmox.Structs.DocumentInfo{

_attachments: "attachments/",
_etag: ""d1028ad3-0000-0c00-0000-630de4900000"",
_rid: "lJweAJDf4xcBAAAAAAAAAA==",
_self: "dbs/lJweAA==/colls/lJweAJDf4xc=/docs/lJweAJDf4xcBAAAAAAAAAA==/",
_ts: 1661854864,
pk: "pk1"

}} iex> Cosmox.Document.delete_document("test_db", "test_container", "1", "pk1") :ok

Link to this function

get_document(database_id, container_id, id, partition_key, struct \\ nil)

View Source
@spec get_document(
  database_id :: binary(),
  container_id :: binary(),
  id :: binary(),
  partition_key :: binary(),
  struct :: term() | nil
) :: response(term())

List all the documents on the given db/container/partition key. By giving the struct in input, the library will try deserialize the list to that.

example

Example

iex> person = %Cosmox.Structs.Tests.Person{ ...> id: "1", ...> pk: "pk1", ...> name: "Some Name", ...> surname: "Some Surname", ...> age: 55 ...> } %Cosmox.Structs.Tests.Person{

age: 55,
id: "1",
name: "Some Name",
pk: "pk1",
surname: "Some Surname"

} iex> Cosmox.Document.create_document("test_db", "test_container", person) {:ok, %Cosmox.Structs.DocumentInfo{

_attachments: "attachments/",
_etag: ""d1028ad3-0000-0c00-0000-630de4900000"",
_rid: "lJweAJDf4xcBAAAAAAAAAA==",
_self: "dbs/lJweAA==/colls/lJweAJDf4xc=/docs/lJweAJDf4xcBAAAAAAAAAA==/",
_ts: 1661854864,
pk: "pk1"

}} iex> Cosmox.Document.get_document("test_db", "test_container", "1", "pk1") {:ok, %{

"_attachments" => "attachments/",
"_etag" => ""d1028ad3-0000-0c00-0000-630de4900000"",
"_rid" => "lJweAJDf4xcBAAAAAAAAAA==",
"_self" => "dbs/lJweAA==/colls/lJweAJDf4xc=/docs/lJweAJDf4xcBAAAAAAAAAA==/",
"_ts" => 1661854864,
"age" => 55,
"id" => "1",
"name" => "Some Name",
"pk" => "pk1",
"surname" => "Some Surname"

} iex> Cosmox.Document.get_document("test_db", "test_container", "1", "pk1", Cosmox.Structs.Tests.Person) {:ok, %Cosmox.Structs.Tests.Person{

age: 55,
id: "1",
name: "Some Name",
pk: "pk1",
surname: "Some Surname"

}}

Link to this function

list_documents(database_id, container_id, partition_key, struct \\ nil)

View Source
@spec list_documents(
  database_id :: binary(),
  container_id :: binary(),
  partition_key :: binary(),
  struct :: term() | nil
) :: response(term())

List all the documents on the given db/container/partition key. By giving the struct in input, the library will try deserialize the list item to that.

examples

Examples

iex> person = %Cosmox.Structs.Tests.Person{ ...> id: "1", ...> pk: "pk1", ...> name: "Some Name", ...> surname: "Some Surname", ...> age: 55 ...> } %Cosmox.Structs.Tests.Person{

age: 55,
id: "1",
name: "Some Name",
pk: "pk1",
surname: "Some Surname"

} iex> Cosmox.Document.create_document("test_db", "test_container", person) {:ok, %Cosmox.Structs.DocumentInfo{

_attachments: "attachments/",
_etag: ""d1028ad3-0000-0c00-0000-630de4900000"",
_rid: "lJweAJDf4xcBAAAAAAAAAA==",
_self: "dbs/lJweAA==/colls/lJweAJDf4xc=/docs/lJweAJDf4xcBAAAAAAAAAA==/",
_ts: 1661854864,
pk: "pk1"

}} iex> map = %{ ...> "id" => "2", ...> "pk" => "pk1", ...> "name" => "Some Other Name", ...> "surname" => "Some Other Surname", ...> "age" => 45 ...> } %{

"age" => 45,
"id" => "2",
"name" => "Some Other Name",
"pk" => "pk1",
"surname" => "Some Other Surname"

} iex> Cosmox.Document.create_document("test_db", "test_container", map) {:ok, %Cosmox.Structs.DocumentInfo{

_attachments: "attachments/",
_etag: ""d302b4a3-0000-0c00-0000-630de9900000"",
_rid: "lJweAJDf4xcCAAAAAAAAAA==",
_self: "dbs/lJweAA==/colls/lJweAJDf4xc=/docs/lJweAJDf4xcCAAAAAAAAAA==/",
_ts: 1661856144,
pk: "pk1"

}} iex> Cosmox.Document.list_documents("test_db", "test_container", "pk1") {:ok, [

%{
  "_attachments" => "attachments/",
  "_etag" => ""d1028ad3-0000-0c00-0000-630de4900000"",
  "_rid" => "lJweAJDf4xcBAAAAAAAAAA==",
  "_self" => "dbs/lJweAA==/colls/lJweAJDf4xc=/docs/lJweAJDf4xcBAAAAAAAAAA==/",
  "_ts" => 1661854864,
  "age" => 55,
  "id" => "1",
  "name" => "Some Name",
  "pk" => "pk1",
  "surname" => "Some Surname"
},
%{
  "_attachments" => "attachments/",
  "_etag" => ""d302b4a3-0000-0c00-0000-630de9900000"",
  "_rid" => "lJweAJDf4xcCAAAAAAAAAA==",
  "_self" => "dbs/lJweAA==/colls/lJweAJDf4xc=/docs/lJweAJDf4xcCAAAAAAAAAA==/",
  "_ts" => 1661856144,
  "age" => 45,
  "id" => "2",
  "name" => "Some Other Name",
  "pk" => "pk1",
  "surname" => "Some Other Surname"
}

]} iex> Cosmox.Document.list_documents("test_db", "test_container", "pk1", Cosmox.Structs.Tests.Person) {:ok, [

%Cosmox.Structs.Tests.Person{
  age: 55,
  id: "1",
  name: "Some Name",
  pk: "pk1",
  surname: "Some Surname"
},
%Cosmox.Structs.Tests.Person{
  age: 45,
  id: "2",
  name: "Some Other Name",
  pk: "pk1",
  surname: "Some Other Surname"
}

]}

Link to this function

patch_document(database_id, container_id, id, partition_key, arg, struct \\ nil)

View Source
@spec patch_document(
  database_id :: binary(),
  container_id :: binary(),
  id :: binary(),
  partition_key :: binary(),
  patch :: {key :: binary(), value :: binary()},
  struct :: term() | nil
) :: response(term())

Patches some fields of an existing document, provided the key of the property, and its value.

example

Example

iex> person = %Cosmox.Structs.Tests.Person{ ...> id: "1", ...> pk: "pk1", ...> name: "Some Name", ...> surname: "Some Surname", ...> age: 55 ...> } %Cosmox.Structs.Tests.Person{

age: 55,
id: "1",
name: "Some Name",
pk: "pk1",
surname: "Some Surname"

} iex> Cosmox.Document.create_document("test_db", "test_container", person) {:ok, %Cosmox.Structs.DocumentInfo{

_attachments: "attachments/",
_etag: ""d1028ad3-0000-0c00-0000-630de4900000"",
_rid: "lJweAJDf4xcBAAAAAAAAAA==",
_self: "dbs/lJweAA==/colls/lJweAJDf4xc=/docs/lJweAJDf4xcBAAAAAAAAAA==/",
_ts: 1661854864,
pk: "pk1"

}} iex> Cosmox.Document.patch_document("test_db", "test_container", "1", "pk1", { ...> :surname |> Atom.to_string(), ...> "Some Other Surname" ...> }) {:ok, %{

"_attachments" => "attachments/",
"_etag" => ""e402e76f-0000-0c00-0000-630e14490000"",
"_rid" => "lJweAJDf4xcBAAAAAAAAAA==",
"_self" => "dbs/lJweAA==/colls/lJweAJDf4xc=/docs/lJweAJDf4xcBAAAAAAAAAA==/",
"_ts" => 1661867081,
"age" => 55,
"id" => "1",
"name" => "Some Name",
"pk" => "pk1",
"surname" => "Some Other Surname"

}}

Link to this function

query_documents(database_id, container_id, partition_key, arg, struct \\ nil)

View Source
@spec query_documents(
  database_id :: binary(),
  container_id :: binary(),
  partition_key :: binary(),
  {query :: binary(), parameters :: [{key :: binary(), value :: any()}]},
  struct :: term() | nil
) :: response(term())

Applies the query to the specified database/container set passed in input, with the given parameters. This function will apply the query only on a particular partition key, that will have to be defined in the query. This function will not apply the partition key automatically: the partition key will have to be specified manually in the query by adding a filter over the pk field of the collection, and by subsequently adding the related parameter in the parameter list.

example

Example

iex> person = %Cosmox.Structs.Tests.Person{ ...> id: "1", ...> pk: "pk1", ...> name: "Some Name", ...> surname: "Some Surname", ...> age: 55 ...> } %Cosmox.Structs.Tests.Person{

age: 55,
id: "1",
name: "Some Name",
pk: "pk1",
surname: "Some Surname"

} iex> Cosmox.Document.create_document("test_db", "test_container", person) {:ok, %Cosmox.Structs.DocumentInfo{

_attachments: "attachments/",
_etag: ""d1028ad3-0000-0c00-0000-630de4900000"",
_rid: "lJweAJDf4xcBAAAAAAAAAA==",
_self: "dbs/lJweAA==/colls/lJweAJDf4xc=/docs/lJweAJDf4xcBAAAAAAAAAA==/",
_ts: 1661854864,
pk: "pk1"

}} iex> Cosmox.Document.query_documents("test_db", "test_container", "pk1", { ...> "SELECT * FROM c WHERE c.name = @p1", ...> [ ...> {"@p1", "Some Name"} ...> ] ...> }, Cosmox.Structs.Tests.Person) {:ok, [

%Cosmox.Structs.Tests.Person{
  age: 55,
  id: "1",
  name: "Some Name",
  pk: "pk1",
  surname: "Some Surname"
}

]}

Link to this function

query_documents_cross_partition(database_id, container_id, arg, struct \\ nil)

View Source
@spec query_documents_cross_partition(
  database_id :: binary(),
  container_id :: binary(),
  {query :: binary(), parameters :: [{key :: binary(), value :: any()}]},
  struct :: term() | nil
) :: response(term())

Applies the query to the specified database/container set passed in input, with the given parameters. This query will span data across partitions.

examples

Examples

iex> person = %Cosmox.Structs.Tests.Person{ ...> id: "1", ...> pk: "pk1", ...> name: "Some Name", ...> surname: "Some Surname", ...> age: 55 ...> } %Cosmox.Structs.Tests.Person{

age: 55,
id: "1",
name: "Some Name",
pk: "pk1",
surname: "Some Surname"

} iex> Cosmox.Document.create_document("test_db", "test_container", person) {:ok, %Cosmox.Structs.DocumentInfo{

_attachments: "attachments/",
_etag: ""d1028ad3-0000-0c00-0000-630de4900000"",
_rid: "lJweAJDf4xcBAAAAAAAAAA==",
_self: "dbs/lJweAA==/colls/lJweAJDf4xc=/docs/lJweAJDf4xcBAAAAAAAAAA==/",
_ts: 1661854864,
pk: "pk1"

}} iex> person_second_part = %Cosmox.Structs.Tests.Person{ ...> id: "2", ...> pk: "pk2", ...> name: "Second pk name", ...> surname: "Second pk surname", ...> age: 45 ...> } %Cosmox.Structs.Tests.Person{

age: 45,
id: "2",
name: "Second pk name",
pk: "pk2",
surname: "Second pk surname"

} iex> Cosmox.Document.create_document("test_db", "test_container", person_second_part) {:ok, %Cosmox.Structs.DocumentInfo{

_attachments: "attachments/",
_etag: ""e502d3e3-0000-0c00-0000-630e181b0000"",
_rid: "lJweAJDf4xcEAAAAAAAAAA==",
_self: "dbs/lJweAA==/colls/lJweAJDf4xc=/docs/lJweAJDf4xcEAAAAAAAAAA==/",
_ts: 1661868059,
pk: "pk2"

}} iex> Cosmox.Document.query_documents_cross_partition("test_db", "test_container", { ...> "SELECT * FROM c WHERE c.age > @p1", ...> [ ...> {"@p1", 30} ...> ] ...> }) {:ok, [

%{
  "_attachments" => "attachments/",
  "_etag" => ""e402ceb5-0000-0c00-0000-630e15030000"",
  "_rid" => "lJweAJDf4xcDAAAAAAAAAA==",
  "_self" => "dbs/lJweAA==/colls/lJweAJDf4xc=/docs/lJweAJDf4xcDAAAAAAAAAA==/",
  "_ts" => 1661867267,
  "age" => 55,
  "id" => "1",
  "name" => "Some Name",
  "pk" => "pk1",
  "surname" => "Some Surname"
},
%{
  "_attachments" => "attachments/",
  "_etag" => ""e502d3e3-0000-0c00-0000-630e181b0000"",
  "_rid" => "lJweAJDf4xcEAAAAAAAAAA==",
  "_self" => "dbs/lJweAA==/colls/lJweAJDf4xc=/docs/lJweAJDf4xcEAAAAAAAAAA==/",
  "_ts" => 1661868059,
  "age" => 45,
  "id" => "2",
  "name" => "Second pk name",
  "pk" => "pk2",
  "surname" => "Second pk surname"
}

]} iex> Cosmox.Document.query_documents_cross_partition("test_db", "test_container", { ...> "SELECT * FROM c WHERE c.age > @p1", ...> [ ...> {"@p1", 50} ...> ] ...> }) {:ok, [

%{
  "_attachments" => "attachments/",
  "_etag" => ""e402ceb5-0000-0c00-0000-630e15030000"",
  "_rid" => "lJweAJDf4xcDAAAAAAAAAA==",
  "_self" => "dbs/lJweAA==/colls/lJweAJDf4xc=/docs/lJweAJDf4xcDAAAAAAAAAA==/",
  "_ts" => 1661867267,
  "age" => 55,
  "id" => "1",
  "name" => "Some Name",
  "pk" => "pk1",
  "surname" => "Some Surname"
}

]}

Link to this function

replace_document(database_id, container_id, id, item, struct \\ nil)

View Source
@spec replace_document(
  database_id :: binary(),
  container_id :: binary(),
  id :: binary(),
  item :: map() | struct(),
  struct :: term() | nil
) :: response(term())

Replaces the content of the document identified by the id and the partition key given in input.

example

Example

iex> person = %Cosmox.Structs.Tests.Person{ ...> id: "1", ...> pk: "pk1", ...> name: "Some Name", ...> surname: "Some Surname", ...> age: 55 ...> } %Cosmox.Structs.Tests.Person{

age: 55,
id: "1",
name: "Some Name",
pk: "pk1",
surname: "Some Surname"

} iex> Cosmox.Document.create_document("test_db", "test_container", person) {:ok, %Cosmox.Structs.DocumentInfo{

_attachments: "attachments/",
_etag: ""d1028ad3-0000-0c00-0000-630de4900000"",
_rid: "lJweAJDf4xcBAAAAAAAAAA==",
_self: "dbs/lJweAA==/colls/lJweAJDf4xc=/docs/lJweAJDf4xcBAAAAAAAAAA==/",
_ts: 1661854864,
pk: "pk1"

}} iex> person =
...> person
...> |> Map.put(:name, "Some Other Name") %Cosmox.Structs.Tests.Person{

age: 55,
id: "1",
name: "Some Other Name",
pk: "pk1",
surname: "Some Surname"

} iex> Cosmox.Document.replace_document("test_db", "test_container", "1", person) {:ok, %{

"_attachments" => "attachments/",
"_etag" => ""e00253d8-0000-0c00-0000-630e0b150000"",
"_rid" => "lJweAJDf4xcBAAAAAAAAAA==",
"_self" => "dbs/lJweAA==/colls/lJweAJDf4xc=/docs/lJweAJDf4xcBAAAAAAAAAA==/",
"_ts" => 1661864725,
"age" => 55,
"id" => "1",
"name" => "Some Name",
"pk" => "pk1",
"surname" => "Some Surname"

}}