ryangrimm/vaporelasticsearch

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()

Package Metadata

Repository: ryangrimm/vaporelasticsearch

Default branch: master

README: README.md