ExTypesense

https://hexdocs.pm/ex_typesense/2.3.2
Admin
ExTypesense is an Elixir client library that adheres to Typesense's OpenAPI specification, enabling...
Tokens:5,189
Snippets:48
Trust Score:9
Update:4 months ago
Show doc for...
Tokens:
Raw
### Example docker-compose.yml for Typesense

Source: https://hexdocs.pm/ex_typesense

An example `docker-compose.yml` file for setting up a local Typesense instance with specified ports, volumes, and command-line arguments.

```yaml
services:
  typesense:
    image: docker.io/typesense/typesense:30.1
    container_name: typesense
    restart: on-failure
    ports:
      - "8107:8107" # internal status
      - "8108:8108" # typesense server
    volumes:
      - ./typesense-data:/data
      - ./typesense-analytics-data:/analytics-data
    command: |
      --data-dir=/data
      --api-key=xyz
      --enable-search-analytics=true
      --analytics-dir=/analytics-data
      --analytics-flush-interval=60
      --analytics-minute-rate-limit=100
      --enable-cors
```

--------------------------------

### Run Local Typesense Instance with Docker Compose

Source: https://hexdocs.pm/ex_typesense

Provides the command to start a local Typesense instance using Docker Compose.

```bash
docker compose up -d
```

--------------------------------

### Get Collection

Source: https://hexdocs.pm/ex_typesense

Retrieves information about a specific collection, with options to customize the request, such as adding cache or retry settings.

```APIDOC
## ExTypesense.get_collection

### Description
Retrieves information about a specific collection, with options to customize the request, such as adding cache or retry settings.

### Method
`ExTypesense.get_collection(collection_name, opts \\ [])`

### Parameters
- **collection_name**: (string) - The name of the collection to retrieve.
- **opts**: (keyword list) - Options for the request, e.g., `req: [retry: false, cache: true]`.

### Request Example
```elixir
ExTypesense.get_collection("companies", req: [retry: false, cache: true])
```

### Response
(Details about the response structure would typically be here, but are not provided in the source text.)
```

--------------------------------

### Configure ExTypesense Credentials via Runtime Config

Source: https://hexdocs.pm/ex_typesense

Demonstrates how to set ExTypesense credentials (API key, host, port, scheme) in `config/runtime.exs` for production environments.

```elixir
# e.g. config/runtime.exs
if config_env() == :prod do # if you'll use this in prod environment
  config :open_api_typesense,
    api_key: "xyz",
    host: "localhost",
    port: 8108,
    scheme: "http"
  ...
```

--------------------------------

### Manually Construct ExTypesense Connection Map

Source: https://hexdocs.pm/ex_typesense

Demonstrates how to manually construct a map for ExTypesense connection credentials, including converting a struct and mapping fields.

```elixir
conn = %Credential{
  node: "localhost",
  secret_key: "xyz",
  port: 8108,
  scheme: "http"
}

conn =
  conn
  |> Map.from_struct()
  |> Map.drop([:node, :secret_key])
  |> Map.put(:host, conn.node)
  |> Map.put(:api_key, conn.secret_key)

# NOTE: create a collection and import documents

```

--------------------------------

### Configure Request Options for Client

Source: https://hexdocs.pm/ex_typesense

Demonstrates how to pass custom request options, such as retry and cache settings, to the built-in Typesense client. This allows for fine-tuning the client's behavior.

```elixir
ExTypesense.get_collection("companies", req: [retry: false, cache: true])
```

--------------------------------

### Configure ExTypesense Credentials for Cloud Hosted Instance

Source: https://hexdocs.pm/ex_typesense

Shows how to configure ExTypesense credentials for a cloud-hosted Typesense instance, including obtaining credentials from the cluster admin interface.

```elixir
config :open_api_typesense,
  api_key: "credential", # Admin API key
  host: "111222333aaabbbcc-9.x9.typesense.net", # Nodes
  port: 443,
  scheme: "https"
```

--------------------------------

### Add ExTypesense to Mix Dependencies

Source: https://hexdocs.pm/ex_typesense

Shows how to add the ExTypesense library to your Elixir project's `mix.exs` file, either from Hex.pm or a GitHub repository.

```elixir
def deps do
  [
    # From default Hex package manager
    {:ex_typesense, "~> 2.3"}

    # Or from GitHub repository, if you want the latest greatest from main branch
    {:ex_typesense, git: "https://github.com/jaeyson/ex_typesense.git"}
  ]
end
```

--------------------------------

### Convert Ecto Struct to Map for ExTypesense Connection

Source: https://hexdocs.pm/ex_typesense

Shows how to convert an Ecto struct to a map and then adjust it to match the expected `OpenApiTypesense.Connection.t()` format for ExTypesense.

```elixir
conn = Map.from_struct(MyApp.Credential)

# NOTE: create a collection and import documents
# first before using the command below
ExTypesense.search(collection_name, query, conn: conn)
```

--------------------------------

### ExTypesense v1 vs v2 API Calls

Source: https://hexdocs.pm/ex_typesense

Illustrates the change in function call syntax for ExTypesense between versions 1 and 2, specifically regarding the `conn` and `opts` parameters.

```elixir
# pre-v2
ExTypesense.list_collections(conn, opts)

# v2
ExTypesense.list_collections(conn: conn)

# another way (v2)
opts = [limit: 1, conn: conn]
ExTypesense.list_collections(opts)
```

--------------------------------

### Set ExTypesense Credentials Dynamically from Ecto Schema

Source: https://hexdocs.pm/ex_typesense

Illustrates how to dynamically set ExTypesense connection credentials by fetching them from an Ecto schema and constructing a connection map.

```elixir
defmodule MyApp.Credential do
  schema "credentials" do
    field :node, :string
    field :secret_key, :string
    field :port, :integer
  end
end

credential = MyApp.Credential |> where(id: ^8888) |> Repo.one()

conn = %{
  host: credential.node,
  api_key: credential.secret_key,
  port: credential.port,
  scheme: "https"
}

# NOTE: create a collection and import documents
# first before using the command below
ExTypesense.search(collection_name, query, conn: conn)
```

--------------------------------

### Typesense Client Configuration

Source: https://hexdocs.pm/ex_typesense

Configures the OpenApiTypesense library to use the custom client module and specifies connection details for the Typesense instance.

```elixir
config :open_api_typesense,
  api_key: "xyz", # Admin API key
  host: "localhost", # Nodes
  port: 8108,
  scheme: "http",
  client: MyApp.CustomClient # <- add this
```

--------------------------------

### Basic Search and Health Check

Source: https://hexdocs.pm/ex_typesense

Demonstrates how to perform a basic search and check the health of the Typesense connection using a map for connection details.

```elixir
ExTypesense.search(collection_name, query, conn: conn)
```

```elixir
conn = %{
    host: "127.0.0.1",
    api_key: "xyz",
    port: 8108,
    scheme: "http"
}

ExTypesense.health(conn: conn)
```

--------------------------------

### Create Collection using Ecto Schema

Source: https://hexdocs.pm/ex_typesense

Defines an Ecto schema for a 'Person' and configures it for ExTypesense, including specifying field types and a default sorting field. This is used to create a collection in Typesense.

```elixir
defmodule Person do
  use Ecto.Schema
  @behaviour ExTypesense

  # In this example, we're adding `persons_id`
  # that points to the id of `persons` schema.

  defimpl Jason.Encoder, for: __MODULE__ do
    def encode(value, opts) do
      value
      |> Map.take([:id, :persons_id, :name, :country])
      |> Enum.map(fn {key, val} ->
        cond do
          key === :id -> {key, to_string(Map.get(value, :id))}
          key === :persons_id -> {key, Map.get(value, :id)}
          true -> {key, val}
        end
      end)
      |> Enum.into(%{})
      |> Jason.Encode.map(opts)
    end
  end

  schema "persons" do
    field(:name, :string)
    field(:country, :string)
    field(:persons_id, :integer, virtual: true)
  end

  @impl ExTypesense
  def get_field_types do
      name = __MODULE__.__schema__(:source)
      primary_field = name <> "_id"

    %{ 
      name: name,
      default_sorting_field: primary_field,
      fields: [
        %{name: primary_field, type: "int32"},
        %{name: "name", type: "string"},
        %{name: "country", type: "string"}
      ]
    }
  end
end
```

```elixir
ExTypesense.create_collection(Person)
```

--------------------------------

### Custom HTTPoison Client Module

Source: https://hexdocs.pm/ex_typesense

Defines a custom client module that implements the OpenApiTypesense.Client behaviour using HTTPoison for making requests to Typesense.

```elixir
defmodule MyApp.CustomClient do
  @behaviour OpenApiTypesense.Client
  
  @impl OpenApiTypesense.Client
  def request(conn, params) do
    url = %URI{
      scheme: conn.scheme,
      host: conn.host,
      port: conn.port,
      path: params.url,
      query: URI.encode_query(params[:query] || %{})
    }
    |> URI.to_string()

    request = %HTTPoison.Request{method: params.method, url: url}

    request = 
      if params[:request] do
        [{content_type, _schema}] = params.request

        headers = [
          {"X-TYPESENSE-API-KEY", conn.api_key}
          {"Content-Type", content_type}
        ]

        %{request | headers: headers}
      else
        request
      end

    request = 
      if params[:body] do
        %{request | body: Jason.encode!(params.body)}
      else
        request
      end

    HTTPoison.request!(request)
  end
end
```

--------------------------------

### Configure Non-Default Finch Adapter

Source: https://hexdocs.pm/ex_typesense

Shows how to configure ExTypesense to use a non-default Finch adapter by specifying a custom Finch pool in the application configuration. This is useful for managing multiple Finch pools.

```elixir
config :open_api_typesense,
  api_key: "XXXXXX",
  #...
  options: [finch: MyApp.CustomFinch] # <- add options
```

--------------------------------

### Import Multiple Documents (Ecto)

Source: https://hexdocs.pm/ex_typesense

Imports multiple documents into Typesense from a list of Ecto records.

```APIDOC
## ExTypesense.import_documents (from Ecto)

### Description
Imports multiple documents into Typesense from a list of Ecto records.

### Method
`ExTypesense.import_documents(list_of_ecto_records)`

### Parameters
- **list_of_ecto_records**: (list) - A list of Ecto records to be indexed.

### Request Example
```elixir
# Assuming Post is an Ecto schema
Post |> Repo.all() |> ExTypesense.import_documents()
```

### Response
(Details about the response structure would typically be here, but are not provided in the source text.)
```

--------------------------------

### Import Multiple Documents using List of Maps

Source: https://hexdocs.pm/ex_typesense

Imports multiple documents into Typesense by providing a list of maps, each representing a document. The collection name is specified as the first argument.

```elixir
multiple_documents = [
  %{ 
    company_name: "Boca Cola",
    doc_companies_id: 827,
    country: "SG"
  },
  %{ 
    company_name: "Motor, Inc.",
    doc_companies_id: 549,
    country: "TW"
  }
]

ExTypesense.import_documents("companies", multiple_documents)
```

--------------------------------

### Import Multiple Documents (Map)

Source: https://hexdocs.pm/ex_typesense

Imports multiple documents into Typesense from a list of maps.

```APIDOC
## ExTypesense.import_documents (from List of Maps)

### Description
Imports multiple documents into Typesense from a list of maps.

### Method
`ExTypesense.import_documents(collection_name, list_of_document_maps)`

### Parameters
- **collection_name**: (string) - The name of the collection where the documents will be indexed.
- **list_of_document_maps**: (list) - A list of maps, where each map represents a document to be indexed.

### Request Example
```elixir
multiple_documents = [
  %{company_name: "Boca Cola", doc_companies_id: 827, country: "SG"},
  %{company_name: "Motor, Inc.", doc_companies_id: 549, country: "TW"}
]

ExTypesense.import_documents("companies", multiple_documents)
```

### Response
(Details about the response structure would typically be here, but are not provided in the source text.)
```

--------------------------------

### Import Multiple Documents using Ecto

Source: https://hexdocs.pm/ex_typesense

Imports multiple documents into Typesense by fetching all records from an Ecto repository and passing the list to the `import_documents` function.

```elixir
Post |> Repo.all() |> ExTypesense.import_documents()
```

--------------------------------

### Search (Basic)

Source: https://hexdocs.pm/ex_typesense

Performs a basic search operation on a collection.

```APIDOC
## ExTypesense.search (Basic)

### Description
Performs a basic search operation on a collection.

### Method
`ExTypesense.search(collection_name, query, conn)`

### Parameters
- **collection_name**: (string) - The name of the collection to search within.
- **query**: (string) - The search query string.
- **conn**: (map) - The connection map for the Typesense server.

### Request Example
```elixir
# Assuming conn is already defined
ExTypesense.search("my_collection", "search term", conn: conn)
```

### Response
(Details about the response structure would typically be here, but are not provided in the source text.)
```

--------------------------------

### Create Collection using Map Schema

Source: https://hexdocs.pm/ex_typesense

Creates a Typesense collection using a map that defines the schema, including field names, types, and the default sorting field. This method is useful when not using Ecto.

```elixir
schema = %{
  name: "companies",
  fields: [
    %{name: "company_name", type: "string"},
    %{name: "companies_id", type: "int32"},
    %{name: "country", type: "string"}
  ],
  default_sorting_field: "companies_id"
}

ExTypesense.create_collection(schema)
```

--------------------------------

### Create Collection from Schema

Source: https://hexdocs.pm/ex_typesense

Creates a new collection in Typesense based on an Ecto schema definition.

```APIDOC
## ExTypesense.create_collection (from Ecto Schema)

### Description
Creates a new collection in Typesense based on an Ecto schema definition.

### Method
`ExTypesense.create_collection(SchemaModule)`

### Parameters
- **SchemaModule**: (module) - The Ecto module that defines the schema and implements the `ExTypesense` behaviour.

### Request Example
```elixir
# Assuming Person module is defined with @behaviour ExTypesense
ExTypesense.create_collection(Person)
```

### Response
(Details about the response structure would typically be here, but are not provided in the source text.)
```

--------------------------------

### Create Collection from Map

Source: https://hexdocs.pm/ex_typesense

Creates a new collection in Typesense using a map that defines the collection's schema.

```APIDOC
## ExTypesense.create_collection (from Map)

### Description
Creates a new collection in Typesense using a map that defines the collection's schema.

### Method
`ExTypesense.create_collection(schema_map)`

### Parameters
- **schema_map**: (map) - A map defining the collection's schema, including `name`, `fields`, and `default_sorting_field`.

### Request Example
```elixir
schema = %{
  name: "companies",
  fields: [
    %{name: "company_name", type: "string"},
    %{name: "companies_id", type: "int32"},
    %{name: "country", type: "string"}
  ],
  default_sorting_field: "companies_id"
}

ExTypesense.create_collection(schema)
```

### Response
(Details about the response structure would typically be here, but are not provided in the source text.)
```

--------------------------------

### Index Single Document using Ecto

Source: https://hexdocs.pm/ex_typesense

Indexes a single document into Typesense by fetching an Ecto record and passing it to the `index_document` function.

```elixir
Post |> Repo.get!(123) |> ExTypesense.index_document()
```

--------------------------------

### Index Single Document (Ecto)

Source: https://hexdocs.pm/ex_typesense

Indexes a single document into Typesense from an Ecto record.

```APIDOC
## ExTypesense.index_document (from Ecto)

### Description
Indexes a single document into Typesense from an Ecto record.

### Method
`ExTypesense.index_document(ecto_record)`

### Parameters
- **ecto_record**: (Ecto.Schema.t) - The Ecto record to be indexed.

### Request Example
```elixir
# Assuming Post is an Ecto schema
Post |> Repo.get!(123) |> ExTypesense.index_document()
```

### Response
(Details about the response structure would typically be here, but are not provided in the source text.)
```

--------------------------------

### Search Documents

Source: https://hexdocs.pm/ex_typesense

Performs a search operation on a Typesense collection. Search parameters like query and fields to search by are provided in a map. The collection can be referenced by its module name or string name.

```elixir
params = %{q: "John Doe", query_by: "name"}

# using string collection name
ExTypesense.search(schema.name, params)

# or module name
ExTypesense.search(Person, params)
```

--------------------------------

### Index Single Document (Map)

Source: https://hexdocs.pm/ex_typesense

Indexes a single document into Typesense from a map.

```APIDOC
## ExTypesense.index_document (from Map)

### Description
Indexes a single document into Typesense from a map.

### Method
`ExTypesense.index_document(collection_name, document_map)` or `ExTypesense.index_document(document_map)`

### Parameters
- **collection_name**: (string) - The name of the collection where the document will be indexed. This is optional if the document map contains the `collection_name` key.
- **document_map**: (map) - A map representing the document to be indexed.

### Request Example
```elixir
document = %{
  collection_name: "companies",
  company_name: "Test",
  doc_companies_id: 103,
  country: "AL"
}

ExTypesense.index_document(document)

# or explicitly pass the collection name
document = %{
  company_name: "Test",
  doc_companies_id: 103,
  country: "AL"
}

ExTypesense.index_document("companies", document)
```

### Response
(Details about the response structure would typically be here, but are not provided in the source text.)
```

--------------------------------

### Test ExTypesense Health Check

Source: https://hexdocs.pm/ex_typesense

A simple Elixir code snippet to verify that the ExTypesense connection is working by calling the `health()` function.

```elixir
ExTypesense.health()
```

--------------------------------

### Index Single Document using Map

Source: https://hexdocs.pm/ex_typesense

Indexes a single document into Typesense using a map. The collection name can be explicitly passed or inferred if the map contains a `collection_name` key.

```elixir
document = %{
  collection_name: "companies",
  company_name: "Test",
  doc_companies_id: 103,
  country: "AL"
}

ExTypesense.index_document(document)

# or explicitly pass the collection name
document = %{
  company_name: "Test",
  doc_companies_id: 103,
  country: "AL"
}

ExTypesense.index_document("companies", document)
```

--------------------------------

### Search Documents

Source: https://hexdocs.pm/ex_typesense

Searches for documents within a specified collection using provided parameters. Supports searching by collection name string or module name.

```APIDOC
## ExTypesense.search

### Description
Searches for documents within a specified collection using provided parameters. Supports searching by collection name string or module name.

### Method
`ExTypesense.search(collection_name, params)`

### Parameters
- **collection_name**: (string or module) - The name of the collection or the Ecto module representing the collection.
- **params**: (map) - A map containing search parameters such as `q` (query) and `query_by`.

### Request Example
```elixir
params = %{q: "John Doe", query_by: "name"}

# using string collection name
ExTypesense.search("companies", params)

# or module name
ExTypesense.search(Person, params)
```

### Response
(Details about the response structure would typically be here, but are not provided in the source text.)
```

--------------------------------

### Health Check

Source: https://hexdocs.pm/ex_typesense

Checks the health status of the Typesense server.

```APIDOC
## ExTypesense.health

### Description
Checks the health status of the Typesense server.

### Method
`ExTypesense.health(conn)`

### Parameters
- **conn**: (map) - The connection map containing Typesense server details (host, api_key, port, scheme).

### Request Example
```elixir
conn = %{
    host: "127.0.0.1",
    api_key: "xyz",
    port: 8108,
    scheme: "http"
}

ExTypesense.health(conn: conn)
```

### Response
(Details about the response structure would typically be here, but are not provided in the source text.)
```
Tokens:
Raw