Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/meilisearch/meilisearch-swift
Swift client for the Meilisearch API
https://github.com/meilisearch/meilisearch-swift
client sdk swift vapor
Last synced: 3 months ago
JSON representation
Swift client for the Meilisearch API
- Host: GitHub
- URL: https://github.com/meilisearch/meilisearch-swift
- Owner: meilisearch
- License: mit
- Created: 2020-04-02T01:23:46.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2023-12-19T18:34:03.000Z (11 months ago)
- Last Synced: 2023-12-20T13:51:54.853Z (11 months ago)
- Topics: client, sdk, swift, vapor
- Language: Swift
- Homepage: https://www.meilisearch.com
- Size: 1.81 MB
- Stars: 83
- Watchers: 6
- Forks: 21
- Open Issues: 21
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-meilisearch - Swift
README
Meilisearch Swift
Meilisearch |
Meilisearch Cloud |
Documentation |
Discord |
Roadmap |
Website |
FAQ
⚡ The Meilisearch API client written for Swift 🍎
**Meilisearch Swift** is the Meilisearch API client for Swift developers.
**Meilisearch** is an open-source search engine. [Learn more about Meilisearch.](https://github.com/meilisearch/meilisearch)
## Table of Contents
- [📖 Documentation](#-documentation)
- [⚡ Supercharge your Meilisearch experience](#-supercharge-your-meilisearch-experience)
- [🔧 Installation](#-installation)
- [🎬 Getting started](#-getting-started)
- [🤖 Compatibility with Meilisearch](#-compatibility-with-meilisearch)
- [💡 Learn more](#-learn-more)
- [⚙️ Contributing](#️-contributing)
- [📜 Demos](#-demos)
## 📖 Documentation
For more information about this API see our [Swift documentation](https://meilisearch.github.io/meilisearch-swift/).
For more information about Meilisearch see our [Documentation](https://docs.meilisearch.com/learn/tutorials/getting_started.html) or our [API References](https://docs.meilisearch.com/reference/api/).
## ⚡ Supercharge your Meilisearch experience
Say goodbye to server deployment and manual updates with [Meilisearch Cloud](https://www.meilisearch.com/cloud?utm_campaign=oss&utm_source=github&utm_medium=meilisearch-swift). Get started with a 14-day free trial! No credit card required.
## 🔧 Installation
### With Cocoapods
[CocoaPods](https://cocoapods.org/) is a dependency manager for Cocoa projects.
**Meilisearch-Swift** is available through CocoaPods. To install it, add the following line to your Podfile:
```ruby
pod 'MeiliSearch'
```
Then, run the following command:
```bash
pod install
```
This will download the latest version of Meilisearch pod and prepare the `xcworkspace`.
### With the Swift Package Manager
The [Swift Package Manager](https://swift.org/package-manager/) is a tool for automating the distribution of Swift code and is integrated into the `swift` compiler.
Once you have your Swift package set up, adding **Meilisearch-Swift** as a dependency is as easy as adding it to the `dependencies` value of your `Package.swift`.
```swift
dependencies: [
.package(url: "https://github.com/meilisearch/meilisearch-swift.git", from: "0.16.0")
]
```
### Run Meilisearch
There are many easy ways to [download and run a Meilisearch instance](https://docs.meilisearch.com/reference/features/installation.html#download-and-launch).
For example, using the `curl` command in your [Terminal](https://itconnect.uw.edu/learn/workshops/online-tutorials/web-publishing/what-is-a-terminal/):
```sh
#Install Meilisearch
curl -L https://install.meilisearch.com | sh
# Launch Meilisearch
./meilisearch --master-key=masterKey
```
NB: you can also download Meilisearch from **Homebrew** or **APT** or even run it using **Docker**.
## 🎬 Getting started
To do a simple search using the client, you can create a Swift script like this:
#### Add documents
```swift
import MeiliSearch
// Create a new client instance of Meilisearch.
// Note: You must provide a fully qualified URL including scheme.
let client = try! MeiliSearch(host: "http://localhost:7700")
struct Movie: Codable, Equatable {
let id: Int
let title: String
let genres: [String]
}
let movies: [Movie] = [
Movie(id: 1, title: "Carol", genres: ["Romance", "Drama"]),
Movie(id: 2, title: "Wonder Woman", genres: ["Action", "Adventure"]),
Movie(id: 3, title: "Life of Pi", genres: ["Adventure", "Drama"]),
Movie(id: 4, title: "Mad Max: Fury Road", genres: ["Adventure", "Science Fiction"]),
Movie(id: 5, title: "Moana", genres: ["Fantasy", "Action"]),
Movie(id: 6, title: "Philadelphia", genres: ["Drama"])
]
let semaphore = DispatchSemaphore(value: 0)
// An index is where the documents are stored.
// The uid is the unique identifier to that index.
let index = client.index("movies")
// If the index 'movies' does not exist, Meilisearch creates it when you first add the documents.
index.addDocuments(
documents: movies,
primaryKey: nil
) { result in
switch result {
case .success(let task):
print(task) // => Task(uid: 0, status: Task.Status.enqueued, ...)
case .failure(let error):
print(error.localizedDescription)
}
semaphore.signal()
}
semaphore.wait()
```
With the `uid` of the task, you can check the status (`enqueued`, `canceled`, `processing`, `succeeded` or `failed`) of your documents addition using the [update endpoint](https://docs.meilisearch.com/learn/advanced/asynchronous_operations.html#task-status).
#### Basic Search
```swift
do {
// Call the search function and wait for the result.
let result: SearchResult = try await client.index("movies").search(SearchParameters(query: "philoudelphia"))
dump(result)
} catch {
print(error.localizedDescription)
}
```
Output:
```bash
MeiliSearch.SearchResult
▿ hits: 1 element
▿ SwiftWork.(unknown context at $10d9e7f3c).Movie
- id: 6
- title: "Philadelphia"
▿ genres: 1 element
- "Drama"
- offset: 0
- limit: 20
- estimatedTotalHits: 1
- facetDistribution: nil
▿ processingTimeMs: Optional(1)
- some: 1
▿ query: Optional("philoudelphia")
- some: "philoudelphia"
```
Since Meilisearch is typo-tolerant, the movie `philadelphia` is a valid search response to `philoudelphia`.
> Note: All package APIs support closure-based results for backwards compatibility. Newer async/await variants are being added under [issue 332](https://github.com/meilisearch/meilisearch-swift/issues/332).
#### Custom Search With Filters
If you want to enable filtering, you must add your attributes to the `filterableAttributes` index setting.
```swift
index.updateFilterableAttributes(["id", "genres"]) { result in
// Handle Result in Closure
}
```
You only need to perform this operation once.
Note that MeiliSearch will rebuild your index whenever you update `filterableAttributes`. Depending on the size of your dataset, this might take time. You can track the process using the [update status](https://docs.meilisearch.com/reference/api/updates.html#get-an-update-status).
Then, you can perform the search:
```swift
let searchParameters = SearchParameters(
query: "wonder",
filter: "id > 1 AND genres = Action"
)
let response: Searchable = try await index.search(searchParameters)
```
```json
{
"hits": [
{
"id": 2,
"title": "Wonder Woman",
"genres": ["Action","Adventure"]
}
],
"offset": 0,
"limit": 20,
"nbHits": 1,
"processingTimeMs": 0,
"query": "wonder"
}
```
## 🤖 Compatibility with Meilisearch
This package guarantees compatibility with [version v1.x of Meilisearch](https://github.com/meilisearch/meilisearch/releases/latest), but some features may not be present. Please check the [issues](https://github.com/meilisearch/meilisearch-swift/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22+label%3Aenhancement) for more info.
## 💡 Learn more
The following sections in our main documentation website may interest you:
- **Manipulate documents**: see the [API references](https://docs.meilisearch.com/reference/api/documents.html) or read more about [documents](https://docs.meilisearch.com/learn/core_concepts/documents.html).
- **Search**: see the [API references](https://docs.meilisearch.com/reference/api/search.html) or follow our guide on [search parameters](https://docs.meilisearch.com/reference/features/search_parameters.html).
- **Manage the indexes**: see the [API references](https://docs.meilisearch.com/reference/api/indexes.html) or read more about [indexes](https://docs.meilisearch.com/learn/core_concepts/indexes.html).
- **Configure the index settings**: see the [API references](https://docs.meilisearch.com/reference/api/settings.html) or follow our guide on [settings parameters](https://docs.meilisearch.com/reference/features/settings.html).
## ⚙️ Contributing
Any new contribution is more than welcome in this project!
If you want to know more about the development workflow or want to contribute, please visit our [contributing guidelines](/CONTRIBUTING.md) for detailed instructions!
## 📜 Demos
To try out a demo you will need to go to its directory in `Demos/`. In that directory you can either:
- Open the SwiftPM project in Xcode and press run, or
- Run `swift build` or `swift run` in the terminal.
### Vapor
Please check the Vapor Demo source code [here](https://github.com/meilisearch/meilisearch-swift/tree/main/Demos/VaporDemo).
### Perfect
Please check the Perfect Demo source code [here](https://github.com/meilisearch/meilisearch-swift/tree/main/Demos/PerfectDemo).
**Meilisearch** provides and maintains many **SDKs and Integration tools** like this one. We want to provide everyone with an **amazing search experience for any kind of project**. If you want to contribute, make suggestions, or just know what's going on right now, visit us in the [integration-guides](https://github.com/meilisearch/integration-guides) repository.