beatsbears / vaporelasticsearch

A Vapor/Swift Elasticsearch client

A Vapor/Swift Elasticsearch Client 🔎

The goal of this project is to provide a comprehensive yet easy to use Elasticsearch client for Swift. The Vapor server side framework has a large community around it so integrating with Vapor was a logical first step. That said, this library should be very easy to port to another framework (Perfect, Kitura) or even use by itself for command line utilities and other such purposes.

Main priorities are to provide index management (field mapping, settings, tokenizers and analyzers), CRUD support and search results with support for aggregations. Currently these goals are all being met on some level.

Warning

This project is under heavy development and the public API has been changing (with no backward compatability) every week. That said, the changes tend to be fairly minor as long as you're diligent with pulling the latest code every week.

High Level Features

• Support for creating, updating, requesting and deletion of documents
• High level construction of the Elasticsearch Query DSL
• Execution of constructed search queries
• Execution of many types of aggregations (more are implemented regurally)
• Population of object models when fetching a document and search results (via Swift Codable support)
• Automatic seralization of object models to Elasticsearch (via Swift Codable support)
• Ability to specify the mapping for index creation
• Support for bulk operations

Elasticsearch Version

All development and testing is being done using the Elasticsearch 6.x series. This has implications around document types as they have been depricated in Elasticsearch 6.0 and will be removed in 7.0. Given that multiple types per index is a thing of the past and this client is a thing of the future, supporting multiple types per index didn't seem like a good fit. If using an older version of Elasticsearch, keep this limitation in mind.

📦 Installation

Package.swift

Add Elasticsearch to the Package dependencies:

dependencies: [
    ...,
    .package(url: "https://github.com/ryangrimm/VaporElasticsearch", .branch("master"))
]

as well as to your target (e.g. "App"):

targets: [
    ...
    .target(
        name: "App",
        dependencies: [... "Elasticsearch" ...]
    ),
    ...
]

Getting started 🚀

Make sure that you've imported Elasticsearch everywhere needed:

import Elasticsearch

Adding the Service

Add the ElasticsearchDatabase in your configure.swift file:

let esConfig = ElasticsearchClientConfig(hostname: "localhost", port: 9200)
let es = try ElasticsearchDatabase(config: esConfig)
var databases = DatabasesConfig()
databases.add(database: es, as: .elasticsearch)
services.register(databases)

Enable Logging

var databases = DatabasesConfig()
databases.enableLogging(on: .elasticsearch)
services.register(databases)

Simple search example

struct Document: Codable {

    var id: String
    var title: String
}

func list(_ req: Request) throws -> Future<[Document]> {

	let query = Query(
	    Match(field: "id", value: "42")
	)

	return req.withNewConnection(to: .elasticsearch) { conn in

	    return try conn.search(
		decodeTo: Document.self,
		index: "documents",
		query: SearchContainer(query)
	    )

	}.map(to: [Document].self ) { searchResponse in

	    guard let hits = searchResponse.hits else { return [Document]() }
	    let results = hits.hits.map { $0.source }
	    return results
	}
}

Creating an index (with filter)

//let client: ElasticsearchClient = ...

let synonymFilter = SynonymFilter(name: "synonym_filter",
	synonyms: ["file, document", "nice, awesome, great"])

let synonymAnalyzer = CustomAnalyzer(
	name: "synonym_analyzer",
	tokenizer: StandardTokenizer(),
	filter: [synonymFilter]))

let index = client.configureIndex(name: "documents")
	.indexSettings(index: IndexSettings(shards: 5, replicas: 1))
	.property(key: "id", type: MapKeyword())
	.property(key: "title", type: MapText(analyzer: synonymAnalyzer))

try index.create()

Deleting an index

//let client: ElasticsearchClient = ...
try client.deleteIndex(name: "documents")

Use bulkto insert documents

//let client: ElasticsearchClient = ...

let doc1 = Document(id: 1, title: "hello world")
let doc2 = Document(id: 5, title: "awesome place")

let bulk = client.bulkOperation()
bulk.defaultHeader.index = "documents"

try bulk.create(doc: doc1, id: String(doc1.id))
try bulk.create(doc: doc2, id: String(doc2.id))
// if you want to overwrite documents, use `bulk.index` instead

try bulk.send()