ExTypesense.Collection (ExTypesense v1.2.0)

View Source

Module for creating, listing and deleting collections and aliases.

In Typesense, a Collection is a group of related Documents that is roughly equivalent to a table in a relational database. When we create a collection, we give it a name and describe the fields that will be indexed when a document is added to the collection.

More here: https://typesense.org/docs/latest/api/collections.html

Summary

Functions

Clone an existing collection's schema (documents are not copied), overrides and synonyms. The actual documents in the collection are not copied, so this is primarily useful for creating new collections from an existing reference template.

Create collection from a map, or module name. Collection name is matched on table name if using Ecto schema by default.

Same as create_collection/1 but passes another connection or opts.

Same as create_collection/2 but explicitly passes all arguments.

Creates collection with timestamped name and points to an alias.

Same as create_collection_with_alias/1 but passes another connection or opts.

Deletes a collection alias. The collection itself is not affected by this action.

Permanently drops a collection by collection name or module name.

Same as drop_collection/3 but passes another connection.

Get a specific collection by string or module name.

Same as get_collection/2 but passes another connection.

Get a specific collection by alias.

Same as get_collection_alias/2 but passes another connection.

List all aliases and the corresponding collections that they map to.

Same as list_collection_aliases/1 but passes another connection.

Returns a summary of all your collections. The collections are returned sorted by creation date, with the most recent collections appearing first.

Same as list_collections/0 but passes another connection or option.

Same as list_collections/1 but passes another connection.

Make changes in a collection's fields: adding, removing or updating an existing field(s). Key name is drop to indicate which field is removed (example described below). Only fields can only be updated at the moment.

Functions

clone_collection(src_coll, new_coll)

(since 1.0.0)
@spec clone_collection(String.t() | module(), String.t()) ::
  {:ok, OpenApiTypesense.CollectionResponse.t()}
  | {:error, OpenApiTypesense.ApiResponse.t()}

Clone an existing collection's schema (documents are not copied), overrides and synonyms. The actual documents in the collection are not copied, so this is primarily useful for creating new collections from an existing reference template.

ExTypesense.clone_collection(MyModule.Accounts.User, "persons")

ExTypesense.clone_collection("persons", "accounts")

clone_collection(src_coll, new_coll, opts)

(since 1.0.0)

Same as clone_collection/2

ExTypesense.clone_collection("persons", "accounts", [])

ExTypesense.clone_collection(MyModule.Accounts.User, "persons", [])

ExTypesense.clone_collection(%{api_key: xyz, host: ...}, "persons", "accounts")

ExTypesense.clone_collection(OpenApiTypesense.Connection.new(), MyModule.Accounts.User, "persons")

clone_collection(conn, module, new_coll, opts)

(since 1.0.0)

Same as clone_collection/3 but passes another connection.

ExTypesense.clone_collection(%{api_key: xyz, host: ...}, "persons", "accounts", [])

ExTypesense.clone_collection(OpenApiTypesense.Connection.new(), "persons", MyModule.Accounts.User, [])

create_collection(schema)

(since 1.0.0)
@spec create_collection(map() | module()) ::
  {:ok, OpenApiTypesense.CollectionResponse.t()}
  | {:error, OpenApiTypesense.ApiResponse.t()}

Create collection from a map, or module name. Collection name is matched on table name if using Ecto schema by default.

Please refer to these list of schema params.

Options

  • src_name (optional): Clone an existing collection's schema (documents are not copied), overrides and synonyms. This option is used primarily by clone_collection/2.

Examples

iex> schema = %{
...>   name: "companies",
...>   fields: [
...>     %{name: "company_name", type: "string"},
...>     %{name: "companies_id", type: "int32"},
...>     %{name: "country", type: "string", facet: true}
...>   ],
...>   default_sorting_field: "companies_id"
...> }
iex> ExTypesense.create_collection(schema)
{:ok, %OpenApiTypesense.CollectionResponse{
  created_at: 1234567890,
  default_sorting_field: "companies_id",
  fields: [...],
  name: "companies",
  num_documents: 0,
  symbols_to_index: [],
  token_separators: []
}}

iex> ExTypesense.create_collection(Person)
{:ok, %OpenApiTypesense.CollectionResponse{
  created_at: 1234567890,
  default_sorting_field: "persons_id",
  fields: [...],
  name: "persons",
  num_documents: 0,
  symbols_to_index: [],
  token_separators: []
}}

create_collection(schema, opts)

(since 1.0.0)
@spec create_collection(
  map() | OpenApiTypesense.Connection.t(),
  map() | module() | keyword()
) ::
  {:ok, OpenApiTypesense.CollectionResponse.t()}
  | {:error, OpenApiTypesense.ApiResponse.t()}

Same as create_collection/1 but passes another connection or opts.

ExTypesense.create_collection(%{api_key: xyz, host: ...}, schema)

ExTypesense.create_collection(OpenApiTypesense.Connection.new(), MyModule.Context)

ExTypesense.create_collection(schema, src_name: "companies")

create_collection(conn, module, opts)

(since 1.0.0)
@spec create_collection(
  map() | OpenApiTypesense.Connection.t(),
  map() | module(),
  keyword()
) ::
  {:ok, OpenApiTypesense.CollectionResponse.t()}
  | {:error, OpenApiTypesense.ApiResponse.t()}

Same as create_collection/2 but explicitly passes all arguments.

ExTypesense.create_collection(%{api_key: xyz, host: ...}, schema, opts)

ExTypesense.create_collection(OpenApiTypesense.Connection.new(), MyModule.Context.Schema, opts)

create_collection_with_alias(schema)

(since 1.1.0)
@spec create_collection_with_alias(map() | module()) ::
  {:ok, OpenApiTypesense.CollectionResponse.t()}
  | {:error, OpenApiTypesense.ApiResponse.t()}

Creates collection with timestamped name and points to an alias.

Use case

When using this function, it will append a timestamp in name and adds an alias based on schema name. E.g. if table name is "bricks", then collection name is "bricks-1738558695" and alias name is "bricks". The reason for this addition can be useful when encountering like full re-indexing

One common use-case for aliases is to reindex your data in the background on a new collection and then switch your application to it without any changes to your code. Source

create_collection_with_alias(schema, opts)

(since 1.1.0)
@spec create_collection_with_alias(
  map() | OpenApiTypesense.Connection.t(),
  map() | module() | keyword()
) ::
  {:ok, OpenApiTypesense.CollectionResponse.t()}
  | {:error, OpenApiTypesense.ApiResponse.t()}

Same as create_collection_with_alias/1 but passes another connection or opts.

ExTypesense.create_collection_with_alias(%{api_key: xyz, host: ...}, schema)

ExTypesense.create_collection_with_alias(OpenApiTypesense.Connection.new(), MyModule.Context)

ExTypesense.create_collection_with_alias(schema, src_name: "companies")

create_collection_with_alias(conn, module, opts)

(since 1.1.0)
@spec create_collection_with_alias(
  map() | OpenApiTypesense.Connection.t(),
  map() | module(),
  keyword()
) ::
  {:ok, OpenApiTypesense.CollectionResponse.t()}
  | {:error, OpenApiTypesense.ApiResponse.t()}

Same as create_collection_with_alias/2 but explicitly passes all arguments.

ExTypesense.create_collection_with_alias(%{api_key: xyz, host: ...}, schema, opts)

ExTypesense.create_collection_with_alias(OpenApiTypesense.Connection.new(), MyModule.Context.Schema, opts)

delete_collection_alias(alias_name)

(since 1.0.0)
@spec delete_collection_alias(String.t()) ::
  {:ok, OpenApiTypesense.CollectionAlias.t()}
  | {:error, OpenApiTypesense.ApiResponse.t()}

Deletes a collection alias. The collection itself is not affected by this action.

delete_collection_alias(alias_name, opts)

(since 1.0.0)

Same as delete_collection_alias/1

ExTypesense.delete_collection_alias("persons_sept_8_2019", [])

ExTypesense.delete_collection_alias(%{api_key: xyz, host: ...}, "persons_sept_8_2019")

ExTypesense.delete_collection_alias(OpenApiTypesense.Connection.new(), "persons_sept_8_2019")

delete_collection_alias(conn, alias_name, opts)

(since 1.0.0)
@spec delete_collection_alias(
  map() | OpenApiTypesense.Connection.t(),
  String.t(),
  keyword()
) ::
  {:ok, OpenApiTypesense.CollectionAlias.t()}
  | {:error, OpenApiTypesense.ApiResponse.t()}
@spec delete_collection_alias(
  map() | OpenApiTypesense.Connection.t(),
  String.t(),
  keyword()
) ::
  {:ok, OpenApiTypesense.CollectionAlias.t()}
  | {:error, OpenApiTypesense.ApiResponse.t()}

Same as delete_collection_alias/2 but passes another connection.

ExTypesense.delete_collection_alias(%{api_key: xyz, host: ...}, "persons_sept_8_2019", [])

ExTypesense.delete_collection_alias(OpenApiTypesense.Connection.new(), "persons_sept_8_2019", [])

drop_collection(collection_name)

(since 1.0.0)
@spec drop_collection(String.t() | module()) ::
  {:ok, OpenApiTypesense.CollectionResponse.t()}
  | {:error, OpenApiTypesense.ApiResponse.t()}

Permanently drops a collection by collection name or module name.

This action cannot be undone. For large collections, this might have an impact on read latencies.

alias not affected

dropping a collection does not remove the referenced alias, only the indexed documents.

drop_collection(name, opts)

(since 1.0.0)

Same as drop_collection/2

ExTypesense.drop_collection("persons", [])

ExTypesense.drop_collection(%{api_key: xyz, host: ...}, "persons")

ExTypesense.drop_collection(OpenApiTypesense.Connection.new(), MyModule.Accounts.User)

drop_collection(conn, module, opts)

(since 1.0.0)

Same as drop_collection/3 but passes another connection.

ExTypesense.drop_collection(%{api_key: xyz, host: ...}, "persons", [])

ExTypesense.drop_collection(OpenApiTypesense.Connection.new(), MyModule.Accounts.User, [])

get_collection(coll_name)

(since 1.0.0)
@spec get_collection(String.t() | module()) ::
  {:ok, OpenApiTypesense.CollectionResponse.t()}
  | {:error, OpenApiTypesense.ApiResponse.t()}

Get a specific collection by string or module name.

get_collection(coll_name, opts)

(since 1.0.0)

Same as get_collection/1

ExTypesense.get_collection("persons", [])

ExTypesense.get_collection(MyModule.Accounts.User, [])

ExTypesense.get_collection(%{api_key: xyz, host: ...}, "persons")

ExTypesense.get_collection(OpenApiTypesense.Connection.new(), MyModule.Accounts.User)

get_collection(conn, module, opts)

(since 1.0.0)

Same as get_collection/2 but passes another connection.

ExTypesense.get_collection(%{api_key: xyz, host: ...}, "persons", [])

ExTypesense.get_collection(OpenApiTypesense.Connection.new(), MyModule.Accounts.User, [])

get_collection_alias(alias_name)

(since 1.0.0)
@spec get_collection_alias(String.t() | module()) ::
  {:ok, OpenApiTypesense.CollectionAlias.t()}
  | {:error, OpenApiTypesense.ApiResponse.t()}

Get a specific collection by alias.

get_collection_alias(alias_name, opts)

(since 1.0.0)
@spec get_collection_alias(
  map() | OpenApiTypesense.Connection.t() | String.t() | module(),
  String.t() | module() | keyword()
) ::
  {:ok, OpenApiTypesense.CollectionAlias.t()}
  | {:error, OpenApiTypesense.ApiResponse.t()}

Same as get_collection_alias/1

ExTypesense.get_collection_alias("persons_sept_8_2019", [])

ExTypesense.get_collection_alias(%{api_key: xyz, host: ...}, "persons_sept_8_2019")

ExTypesense.get_collection_alias(OpenApiTypesense.Connection.new(), "persons_sept_8_2019")

get_collection_alias(conn, module, opts)

(since 1.0.0)
@spec get_collection_alias(
  map() | OpenApiTypesense.Connection.t(),
  String.t() | module(),
  keyword()
) ::
  {:ok, OpenApiTypesense.CollectionAlias.t()}
  | {:error, OpenApiTypesense.ApiResponse.t()}

Same as get_collection_alias/2 but passes another connection.

ExTypesense.get_collection_alias(%{api_key: xyz, host: ...}, "persons_sept_8_2019", [])

ExTypesense.get_collection_alias(OpenApiTypesense.Connection.new(), "persons_sept_8_2019", [])

list_collection_aliases()

(since 1.0.0)
@spec list_collection_aliases() ::
  {:ok, OpenApiTypesense.CollectionAliasesResponse.t()} | :error

List all aliases and the corresponding collections that they map to.

list_collection_aliases(opts)

(since 1.0.0)
@spec list_collection_aliases(map() | OpenApiTypesense.Connection.t() | keyword()) ::
  {:ok, OpenApiTypesense.CollectionAliasesResponse.t()} | :error

Same as list_collection_aliases/0

ExTypesense.list_collection_aliases([])

ExTypesense.list_collection_aliases(%{api_key: xyz, host: ...})

ExTypesense.list_collection_aliases(OpenApiTypesense.Connection.new())

list_collection_aliases(conn, opts)

(since 1.0.0)
@spec list_collection_aliases(
  map() | OpenApiTypesense.Connection.t(),
  keyword()
) :: {:ok, OpenApiTypesense.CollectionAliasesResponse.t()} | :error

Same as list_collection_aliases/1 but passes another connection.

ExTypesense.list_collection_aliases(%{api_key: xyz, host: ...}, [])

ExTypesense.list_collection_aliases(OpenApiTypesense.Connection.new(), [])

list_collections()

(since 1.0.0)
@spec list_collections() :: {:ok, [OpenApiTypesense.CollectionResponse.t()]} | :error

Returns a summary of all your collections. The collections are returned sorted by creation date, with the most recent collections appearing first.

Options

  • limit: Limit results in paginating on collection listing.
  • offset: Skip a certain number of results and start after that.
  • exclude_fields: Exclude the field definitions from being returned in the response.

list_collections(opts)

(since 1.0.0)
@spec list_collections(map() | OpenApiTypesense.Connection.t() | keyword()) ::
  {:ok, [OpenApiTypesense.CollectionResponse.t()]} | :error

Same as list_collections/0 but passes another connection or option.

ExTypesense.list_collections(OpenApiTypesense.Connection.new())

ExTypesense.list_collections(%{api_key: xyz, host: ...})

ExTypesense.list_collections(exclude_fields: "fields", limit: 10)

list_collections(conn, opts)

(since 1.0.0)
@spec list_collections(
  map() | OpenApiTypesense.Connection.t(),
  keyword()
) :: {:ok, [OpenApiTypesense.CollectionResponse.t()]} | :error

Same as list_collections/1 but passes another connection.

ExTypesense.list_collections(%{api_key: xyz, host: ...}, limit: 10)

ExTypesense.list_collections(OpenApiTypesense.Connection.new(), exclude_fields: "fields", limit: 10)

update_collection_fields(name, fields)

(since 1.0.0)
@spec update_collection_fields(String.t() | module(), map()) ::
  {:ok, OpenApiTypesense.CollectionUpdateSchema.t()}
  | {:error, OpenApiTypesense.ApiResponse.t()}

Make changes in a collection's fields: adding, removing or updating an existing field(s). Key name is drop to indicate which field is removed (example described below). Only fields can only be updated at the moment.

Typesense special field id

Typesense supports updating all fields except the id field (since it's a special field within Typesense). Do not confuse id of Typesense with Ecto Schema or DB record(s).

Which version supports this function

We can update the collection's fields, starting on version 27.0.rc22 and above.

Examples

iex> fields = %{
...>  fields: [
...>    %{name: "num_employees", drop: true},
...>    %{name: "company_category", type: "string"},
...>  ],
...> }
iex> ExTypesense.update_collection_fields("companies", fields)
%OpenApiTypesense.CollectionUpdateSchema{
  fields: [
    ...
  ]
}

update_collection_fields(name, fields, opts)

(since 1.0.0)
@spec update_collection_fields(
  map() | OpenApiTypesense.Connection.t() | String.t() | module(),
  String.t() | module() | map(),
  map() | keyword()
) ::
  {:ok, OpenApiTypesense.CollectionUpdateSchema.t()}
  | {:error, OpenApiTypesense.ApiResponse.t()}

Same as update_collection_fields/2

ExTypesense.update_collection_fields("persons", fields, [])

ExTypesense.update_collection_fields(%{api_key: xyz, host: ...}, "persons", fields)

ExTypesense.update_collection_fields(OpenApiTypesense.Connection.new(), MyModule.Accounts.User, fields)

update_collection_fields(conn, module, fields, opts)

(since 1.0.0)
@spec update_collection_fields(
  map() | OpenApiTypesense.Connection.t(),
  String.t() | module(),
  map(),
  keyword()
) ::
  {:ok, OpenApiTypesense.CollectionUpdateSchema.t()}
  | {:error, OpenApiTypesense.ApiResponse.t()}

Same as update_collection_fields/3 but passes another connection.

ExTypesense.update_collection_fields(%{api_key: xyz, host: ...}, "persons", fields, [])

ExTypesense.update_collection_fields(OpenApiTypesense.Connection.new(), MyModule.Accounts.User, fields, [])

upsert_collection_alias(alias_name, collection_name)

(since 1.0.0)
@spec upsert_collection_alias(String.t(), String.t() | module()) ::
  {:ok, OpenApiTypesense.CollectionAlias.t()}
  | {:error, OpenApiTypesense.ApiResponse.t()}

Upserts a collection alias.

An alias is a virtual collection name that points to a real collection. If you're familiar with symbolic links on Linux, it's very similar to that. Aliases are useful when you want to reindex your data in the background on a new collection and switch your application to it without any changes to your code.

collection_name can either be a string or module name

upsert_collection_alias(alias_name, coll_name, opts)

(since 1.0.0)
@spec upsert_collection_alias(
  map() | OpenApiTypesense.Connection.t() | String.t(),
  String.t() | module(),
  String.t() | module() | keyword()
) ::
  {:ok, OpenApiTypesense.CollectionAlias.t()}
  | {:error, OpenApiTypesense.ApiResponse.t()}

Same as upsert_collection_alias/2

ExTypesense.upsert_collection_alias("persons_sept_8_2019", "persons", [])

ExTypesense.upsert_collection_alias(%{api_key: xyz, host: ...}, "persons_sept_8_2019", "persons")

ExTypesense.upsert_collection_alias(OpenApiTypesense.Connection.new(), "persons_sept_8_2019", MyModule.Accounts.Person)

upsert_collection_alias(conn, alias_name, module, opts)

(since 1.0.0)
@spec upsert_collection_alias(
  map() | OpenApiTypesense.Connection.t(),
  String.t(),
  String.t() | module(),
  keyword()
) ::
  {:ok, OpenApiTypesense.CollectionAlias.t()}
  | {:error, OpenApiTypesense.ApiResponse.t()}

Same as upsert_collection_alias/3 but passes another connection.

ExTypesense.upsert_collection_alias(%{api_key: xyz, host: ...}, "persons_sept_8_2019", "persons", [])

ExTypesense.upsert_collection_alias(OpenApiTypesense.Connection.new(), "persons_sept_8_2019", MyModule.Accounts.Person, [])