Create a collection and point it to alias (#68)

Author: jaeyson

.gitignore

@@ -25,6 +25,8 @@ ex_typesense-*.tar
 # Temporary files, for example, from tests.
 /tmp/
 
+*.env
+
 # Zed editor
 /.zed/
 
@@ -34,4 +36,4 @@ ex_typesense-*.tar
 
 # Misc.
 .elixir_ls
-**.DS_Store
+*.DS_Store

CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## major.minor.patch (yyyy.mm.dd)
 
+## 1.1.0 (2025.03.02)
+
+### Added
+
+* `Collection.create_collection_with_alias/1`.
+* Allow module name (atom) to be passed as alias name in `Collection.create_collection_with_alias/1`.
+* Typespec to pass also omodule name (atom) for `Collection.create_collection_with_alias/1`.
+* Separate dev and test environments.
+
+### Fixed
+
+* Typespecs for `Search.multi_search_ecto`.
+* Return values of `Search.multi_search_ecto` for `search_test.exs`.
+
+### Deprecated
+
+* `Collection.get_collection_name/1`
+
 ## 1.0.2 (2025.01.30)
 
 ### Changed

README.md

@@ -85,7 +85,7 @@ Add `:ex_typesense` to your list of dependencies in the Elixir project config fi
 def deps do
   [
     # From default Hex package manager
-    {:ex_typesense, "~> 1.0"}
+    {:ex_typesense, "~> 1.1"}
 
     # Or from GitHub repository, if you want the latest greatest from main branch
     {:ex_typesense, git: "https://github.com/jaeyson/ex_typesense.git"}

config/config.exs

@@ -1,9 +1,5 @@
 import Config
 
-if config_env() in [:dev, :test] do
-  config :open_api_typesense,
-    api_key: "xyz",
-    host: "localhost",
-    port: 8108,
-    scheme: "http"
-end
+# Import environment specific config. This must remain at the bottom
+# of this file so it overrides the configuration defined above.
+import_config "#{config_env()}.exs"

config/dev.exs

@@ -0,0 +1,7 @@
+import Config
+
+config :open_api_typesense,
+  api_key: "xyz",
+  host: "localhost",
+  port: 8108,
+  scheme: "http"

config/test.exs

@@ -0,0 +1,9 @@
+import Config
+
+config :open_api_typesense,
+  api_key: "xyz",
+  host: "localhost",
+  port: 8108,
+  scheme: "http",
+  max_retries: 0,
+  retry: false

lib/ex_typesense.ex

@@ -1,5 +1,5 @@
 defmodule ExTypesense do
-  @moduledoc since: "0.1.0"
+  @moduledoc since: "1.0.0"
 
   @moduledoc """
   Public API functions to interact with Typesense.
@@ -103,9 +103,13 @@ defmodule ExTypesense do
   defdelegate list_collections(conn, opts), to: ExTypesense.Collection
 
   defdelegate create_collection(schema), to: ExTypesense.Collection
-  defdelegate create_collection(conn_or_schema, schema_or_opts), to: ExTypesense.Collection
+  defdelegate create_collection(conn, schema), to: ExTypesense.Collection
   defdelegate create_collection(conn, schema, opts), to: ExTypesense.Collection
 
+  defdelegate create_collection_with_alias(schema), to: ExTypesense.Collection
+  defdelegate create_collection_with_alias(conn, schema), to: ExTypesense.Collection
+  defdelegate create_collection_with_alias(conn, schema, opts), to: ExTypesense.Collection
+
   defdelegate clone_collection(src_coll, new_coll), to: ExTypesense.Collection
   defdelegate clone_collection(conn, src_coll, new_coll), to: ExTypesense.Collection
   defdelegate clone_collection(conn, src_coll, new_coll, opts), to: ExTypesense.Collection
@@ -114,8 +118,13 @@ defmodule ExTypesense do
   defdelegate get_collection(conn, coll_name), to: ExTypesense.Collection
   defdelegate get_collection(conn, coll_name, opts), to: ExTypesense.Collection
 
+  @deprecated "Use Collection.get_collection_alias/1 instead"
   defdelegate get_collection_name(alias_name), to: ExTypesense.Collection
+
+  @deprecated "Use Collection.get_collection_alias/2 instead"
   defdelegate get_collection_name(conn, alias_name), to: ExTypesense.Collection
+
+  @deprecated "Use Collection.get_collection_alias/3 instead"
   defdelegate get_collection_name(conn, alias_name, opts), to: ExTypesense.Collection
 
   defdelegate drop_collection(name), to: ExTypesense.Collection

lib/ex_typesense/cluster.ex

@@ -355,7 +355,7 @@ defmodule ExTypesense.Cluster do
   The follower node that you run this operation against will become
   the new leader, once this command succeeds.
   """
-  @spec vote :: {:ok, SuccessStatus.t()} | :error
+  @spec vote :: {:ok, OpenApiTypesense.SuccessStatus.t()} | :error
   def vote do
     vote([])
   end

lib/ex_typesense/collection.ex

@@ -69,6 +69,80 @@ defmodule ExTypesense.Collection do
     OpenApiTypesense.Collections.get_collections(conn, opts)
   end
 
+  @doc """
+  Creates collection with timestamped name and points to an alias.
+
+  > #### Use case {: .warning}
+  >
+  > 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](https://typesense.org/docs/guide/syncing-data-into-typesense.html#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](https://typesense.org/docs/latest/api/collection-alias.html#use-case)
+  """
+  @doc since: "1.1.0"
+  @spec create_collection_with_alias(map() | module()) ::
+          {:ok, OpenApiTypesense.CollectionResponse.t()}
+          | {:error, OpenApiTypesense.ApiResponse.t()}
+  def create_collection_with_alias(schema) do
+    create_collection_with_alias(schema, [])
+  end
+
+  @doc """
+  Same as [create_collection_with_alias/1](`create_collection_with_alias/1`) but passes another connection or opts.
+
+  ```elixir
+  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")
+  ```
+  """
+  @doc since: "1.1.0"
+  @spec create_collection_with_alias(map() | Connection.t(), map() | module() | keyword()) ::
+          {:ok, OpenApiTypesense.CollectionResponse.t()}
+          | {:error, OpenApiTypesense.ApiResponse.t()}
+  def create_collection_with_alias(schema, opts) when is_list(opts) do
+    Connection.new() |> create_collection_with_alias(schema, opts)
+  end
+
+  def create_collection_with_alias(conn, schema) do
+    create_collection_with_alias(conn, schema, [])
+  end
+
+  @doc """
+  Same as [create_collection_with_alias/2](`create_collection_with_alias/2`) but explicitly passes all arguments.
+
+  ```elixir
+  ExTypesense.create_collection_with_alias(%{api_key: xyz, host: ...}, schema, opts)
+
+  ExTypesense.create_collection_with_alias(OpenApiTypesense.Connection.new(), MyModule.Context.Schema, opts)
+  ```
+  """
+  @doc since: "1.1.0"
+  @spec create_collection_with_alias(map() | Connection.t(), map() | module(), keyword()) ::
+          {:ok, OpenApiTypesense.CollectionResponse.t()}
+          | {:error, OpenApiTypesense.ApiResponse.t()}
+  def create_collection_with_alias(conn, module, opts) when is_atom(module) do
+    schema = module.get_field_types()
+    create_collection_with_alias(conn, schema, opts)
+  end
+
+  def create_collection_with_alias(conn, schema, opts) do
+    coll_name = Map.get(schema, "name") || Map.get(schema, :name)
+    coll_name_ts = "#{coll_name}-#{DateTime.utc_now() |> DateTime.to_unix()}"
+    updated_schema = Map.put(schema, :name, coll_name_ts)
+    coll = create_collection(conn, updated_schema, opts)
+    upsert_collection_alias(conn, coll_name, coll_name_ts)
+
+    coll
+  end
+
   @doc """
   Create collection from a map, or module name. Collection name
   is matched on table name if using Ecto schema by default.
@@ -306,6 +380,7 @@ defmodule ExTypesense.Collection do
   Get the collection name by alias.
   """
   @doc since: "1.0.0"
+  @deprecated "Use Collection.get_collection_alias/1 instead"
   @spec get_collection_name(String.t()) ::
           {:ok, OpenApiTypesense.CollectionAlias.t()} | {:error, OpenApiTypesense.ApiResponse.t()}
   def get_collection_name(alias_name) do
@@ -322,6 +397,7 @@ defmodule ExTypesense.Collection do
   ```
   """
   @doc since: "1.0.0"
+  @deprecated "Use Collection.get_collection_alias/2 instead"
   @spec get_collection_name(map() | Connection.t() | String.t(), String.t() | keyword()) ::
           {:ok, OpenApiTypesense.CollectionAlias.t()} | {:error, OpenApiTypesense.ApiResponse.t()}
   def get_collection_name(alias_name, opts) when is_list(opts) do
@@ -342,6 +418,7 @@ defmodule ExTypesense.Collection do
   ```
   """
   @doc since: "1.0.0"
+  @deprecated "Use Collection.get_collection_alias/3 instead"
   @spec get_collection_name(map() | Connection.t(), String.t(), keyword()) ::
           {:ok, OpenApiTypesense.CollectionAlias.t()} | {:error, OpenApiTypesense.ApiResponse.t()}
   def get_collection_name(conn, alias_name, opts) when is_binary(alias_name) do
@@ -402,7 +479,11 @@ defmodule ExTypesense.Collection do
   ```
   """
   @doc since: "1.0.0"
-  @spec update_collection_fields(map() | Connection.t(), String.t() | module(), map() | keyword()) ::
+  @spec update_collection_fields(
+          map() | Connection.t() | String.t() | module(),
+          String.t() | module() | map(),
+          map() | keyword()
+        ) ::
           {:ok, OpenApiTypesense.CollectionUpdateSchema.t()}
           | {:error, OpenApiTypesense.ApiResponse.t()}
   def update_collection_fields(name, fields, opts) when is_list(opts) do
@@ -547,10 +628,10 @@ defmodule ExTypesense.Collection do
   end
 
   @doc """
-  Get a specific collection alias.
+  Get a specific collection by alias.
   """
   @doc since: "1.0.0"
-  @spec get_collection_alias(String.t()) ::
+  @spec get_collection_alias(String.t() | module()) ::
           {:ok, OpenApiTypesense.CollectionAlias.t()} | {:error, OpenApiTypesense.ApiResponse.t()}
   def get_collection_alias(alias_name) do
     get_collection_alias(alias_name, [])
@@ -568,7 +649,10 @@ defmodule ExTypesense.Collection do
   ```
   """
   @doc since: "1.0.0"
-  @spec get_collection_alias(map() | Connection.t() | String.t(), String.t() | keyword()) ::
+  @spec get_collection_alias(
+          map() | Connection.t() | String.t() | module(),
+          String.t() | module() | keyword()
+        ) ::
           {:ok, OpenApiTypesense.CollectionAlias.t()} | {:error, OpenApiTypesense.ApiResponse.t()}
   def get_collection_alias(alias_name, opts) when is_list(opts) do
     Connection.new() |> get_collection_alias(alias_name, opts)
@@ -588,8 +672,13 @@ defmodule ExTypesense.Collection do
   ```
   """
   @doc since: "1.0.0"
-  @spec get_collection_alias(map() | Connection.t(), String.t(), keyword()) ::
+  @spec get_collection_alias(map() | Connection.t(), String.t() | module(), keyword()) ::
           {:ok, OpenApiTypesense.CollectionAlias.t()} | {:error, OpenApiTypesense.ApiResponse.t()}
+  def get_collection_alias(conn, module, opts) when is_atom(module) do
+    alias_name = module.__schema__(:source)
+    get_collection_alias(conn, alias_name, opts)
+  end
+
   def get_collection_alias(conn, alias_name, opts) do
     OpenApiTypesense.Collections.get_alias(conn, alias_name, opts)
   end
@@ -623,14 +712,18 @@ defmodule ExTypesense.Collection do
   ```
   """
   @doc since: "1.0.0"
-  @spec upsert_collection_alias(map() | Connection.t(), String.t(), String.t() | module()) ::
+  @spec upsert_collection_alias(
+          map() | Connection.t() | String.t(),
+          String.t() | module(),
+          String.t() | module() | keyword()
+        ) ::
           {:ok, OpenApiTypesense.CollectionAlias.t()} | {:error, OpenApiTypesense.ApiResponse.t()}
   def upsert_collection_alias(alias_name, coll_name, opts) when is_list(opts) do
     Connection.new() |> upsert_collection_alias(alias_name, coll_name, opts)
   end
 
-  def upsert_collection_alias(conn, alias_name, collection_name) do
-    upsert_collection_alias(conn, alias_name, collection_name, [])
+  def upsert_collection_alias(conn, alias_name, coll_name) do
+    upsert_collection_alias(conn, alias_name, coll_name, [])
   end
 
   @doc """

lib/ex_typesense/conversation.ex

@@ -120,7 +120,7 @@ defmodule ExTypesense.Conversation do
   ```
   """
   @doc since: "1.0.0"
-  @spec get_model(map() | ConnString.t(), String.t(), keyword()) ::
+  @spec get_model(map() | Connection.t(), String.t(), keyword()) ::
           {:ok, OpenApiTypesense.ConversationModelSchema.t()} | :error
   def get_model(conn, model_id, opts) do
     OpenApiTypesense.Conversations.retrieve_conversation_model(conn, model_id, opts)

lib/ex_typesense/document.ex

@@ -142,8 +142,8 @@ defmodule ExTypesense.Document do
       ...> ExTypesense.import_documents("posts", posts)
   """
   @doc since: "1.0.0"
-  @spec import_documents(String.t() | module(), list(struct()) | list(map())) ::
-          {:ok, String.t()} | {:error, OpenApiTypesense.ApiResponse.t()}
+  @spec import_documents(String.t() | module(), [struct()] | [map()]) ::
+          {:ok, [map()]} | {:error, OpenApiTypesense.ApiResponse.t()}
   def import_documents(coll_name, docs) do
     import_documents(coll_name, docs, [])
   end
@@ -166,15 +166,15 @@ defmodule ExTypesense.Document do
   @doc since: "1.0.0"
   @spec import_documents(
           map() | Connection.t() | String.t() | module(),
-          String.t() | list(struct()) | list(map()),
-          list(struct()) | list(map()) | keyword()
+          String.t() | [struct()] | [map()],
+          [struct()] | [map()] | keyword()
         ) ::
-          {:ok, String.t()} | {:error, OpenApiTypesense.ApiResponse.t()}
+          {:ok, [map()]} | {:error, OpenApiTypesense.ApiResponse.t()}
   def import_documents(conn, coll_name, documents) when is_map(conn) and is_list(documents) do
     import_documents(conn, coll_name, documents, [])
   end
 
-  def import_documents(coll_name, docs, opts) when is_list(opts) do
+  def import_documents(coll_name, docs, opts) when is_list(docs) and is_list(opts) do
     Connection.new() |> import_documents(coll_name, docs, opts)
   end
 
@@ -191,10 +191,10 @@ defmodule ExTypesense.Document do
   @spec import_documents(
           map() | Connection.t(),
           String.t() | module(),
-          list(struct()) | list(map()),
+          [struct()] | [map()],
           keyword()
         ) ::
-          {:ok, String.t()} | {:error, OpenApiTypesense.ApiResponse.t()}
+          {:ok, [map()]} | {:error, OpenApiTypesense.ApiResponse.t()}
   def import_documents(conn, module, docs, opts) when is_atom(module) do
     coll_name = module.__schema__(:source)
     import_documents(conn, coll_name, docs, opts)