• Stars
    star
    59
  • Rank 488,320 (Top 10 %)
  • Language
    Scala
  • License
    MIT License
  • Created about 7 years ago
  • Updated 2 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

ArangoDB client written in Scala

Scarango

CI Gitter Maven Central Latest version

ArangoDB client written in Scala

Setup

Scarango is published to Sonatype OSS and Maven Central currently supporting Scala and Scala.js (core only) on 2.13 and 3.

Configuring the driver in SBT requires:

libraryDependencies += "com.outr" %% "scarango-driver" % "3.20.0"

Or in Mill:

ivy"com.outr::scarango-driver:3.20.0"

Introduction

Scarango wraps ArangoDB's Java library to provide lots of additional features and Scala-specific functionality. We utilize cats-effect and fs2 for a more modern asynchronous approach. Previous to 3.0, we utilized direct HTTP RESTful calls and Futures, but the performance benefits of Java's library made a migration worthwhile.

Getting Started

Although there are a few different ways we can utilize Scarango to interact with ArangoDB, the cleanest and most powerful approach is to utilize the Graph layer to set up our database structure and interact with it in a type-safe way. For example:

Database configuration

import com.outr.arango.{Document, DocumentModel, Field, Graph, Id, Index}
import com.outr.arango.collection.DocumentCollection
import com.outr.arango.query._
import fabric.rw._
import cats.effect.unsafe.implicits.global

// Case class to represent a person collection
case class Person(name: String, age: Int, _id: Id[Person] = Person.id()) extends Document[Person]

// We use the companion object to represent additional information about the collection
object Person extends DocumentModel[Person] {
  override implicit val rw: RW[Person] = RW.gen

  val name: Field[String] = field("name")
  val age: Field[Int] = field("age")

  override def indexes: List[Index] = List(
    name.index.persistent()
  )

  override val collectionName: String = "people"
}

// We represent our entire database here referencing all collections
object Database extends Graph("example") {
  val people: DocumentCollection[Person, Person.type] = vertex(Person)
}

This is the basic setup of a single-collection database. Notice the RW in the companion object. That is defined using Fabric for conversion to/from JSON for storage in the database. All fields aren't required to be defined, but it will help us when we want to write simple queries in a type-safe way or when defining things like indexes.

Initialization

The next thing we need to do is initialize the database:

Database.init().unsafeRunSync()

NOTE: We're adding .unsafeRunSync() at the end of each call for the documentation generation to get the result. Under normal circumstances this is not the ideal way to execute a cats-effect IO.

Truncate the database

We can easily clear out everything out of the database:

Database.truncate().unsafeRunSync()

Inserting into the database

A simple insert of a record into the database:

Database.people.insert(Person("User 1", 30)).unsafeRunSync()
// res2: com.outr.arango.core.CreateResult[Person] = CreateResult(
//   key = None,
//   id = None,
//   rev = None,
//   document = Person(
//     name = "User 1",
//     age = 30,
//     _id = Id(value = "Ncx2NMcIpYGtWe9sOd8byYLRuYOCPrnH", collection = "people")
//   ),
//   newDocument = None,
//   oldDocument = None
// )

We can also do batch record insertion:

Database.people.batch.insert(List(
    Person("Adam", 21),
    Person("Bethany", 19)
)).unsafeRunSync()
// res3: com.outr.arango.core.CreateResults[Person] = CreateResults(
//   results = List()
// )

You can also use the Database.people.stream to cross-stream records into the database.

Querying

In order to get the data out that we just inserted we can do a simple AQL query:

Database
  .people
  .query(aql"FOR p IN ${Database.people} RETURN p")
  .toList
  .unsafeRunSync()
// res4: List[Person] = List(
//   Person(
//     name = "User 1",
//     age = 30,
//     _id = Id(value = "Ncx2NMcIpYGtWe9sOd8byYLRuYOCPrnH", collection = "people")
//   ),
//   Person(
//     name = "Adam",
//     age = 21,
//     _id = Id(value = "b61wDJm3nMePIBhzHXpE8jOD52NRvL1V", collection = "people")
//   ),
//   Person(
//     name = "Bethany",
//     age = 19,
//     _id = Id(value = "Ps4IYa9Wfge3y0lwMw3Yxs6ln3CsW3cg", collection = "people")
//   )
// )

For an example of data conversion in the result, if we want to only get the person's name back:

Database
  .people
  .query(aql"FOR p IN ${Database.people} RETURN p.name")
  .as[String]
  .toList
  .unsafeRunSync()
// res5: List[String] = List("Adam", "Bethany", "User 1")

For more examples see the specs: https://github.com/outr/scarango/blob/master/driver/src/test/scala/spec/GraphSpec.scala

TODO

  • Improved ScalaDocs
  • Add AQL compile-time validation support (revive from 2.x)

More Repositories

1

scribe

The fastest logging library in the world. Built from scratch in Scala and programmatically configurable.
Scala
487
star
2

youi

Next generation user interface and application development in Scala and Scala.js for web, mobile, and desktop.
Scala
209
star
3

reactify

The first and only true Functional Reactive Programming framework for Scala.
Scala
82
star
4

scalarelational

Type-Safe framework for defining, modifying, and querying SQL databases
Scala
58
star
5

lucene4s

Light-weight convenience wrapper around Lucene to simplify complex tasks and add Scala sugar.
Scala
54
star
6

media4s

Scala command-line wrapper around ffmpeg, ffprobe, ImageMagick, and other tools relating to media.
Scala
32
star
7

perfolation

Performance focused interpolation
Scala
28
star
8

profig

Powerful configuration management for Scala (JSON, properties, command-line arguments, and environment variables)
Scala
27
star
9

sgine

Scala Engine for OpenGL-based Desktop, Android, and iOS game and business development.
Scala
22
star
10

mailgun4s

Mailgun API implementation in Scala
Scala
17
star
11

neo4akka

Neo4j Scala client using Akka-Http
Scala
15
star
12

powerscala

Powerful framework providing many useful utilities and features on top of the Scala language.
Scala
15
star
13

scala-stripe

Complete Browser and Server client integration of Stripe in Scala and Scala.js
Scala
12
star
14

jefe

Manages installation, updating, downloading, launching, error reporting, and more for your application.
Scala
8
star
15

spice

Powerful client / server technology for Scala
Scala
7
star
16

googleapi.scala.js

Wrapper around Google APIs
Scala
6
star
17

scalajs-pixijs

Scala.js facade for Pixi.js
JavaScript
6
star
18

giant-scala

Advanced functionality for working with MongoDB in Scala
Scala
6
star
19

scalapass

Useful tools for managing storage and validation of passwords in Scala applications
Scala
5
star
20

pdf4s

Simplified wrapper to create PDFs in Scala
Scala
5
star
21

outrgl

DEPRECATED: Please use http://youi.io going forward
Scala
5
star
22

nextui

UI Abstraction Framework
Scala
4
star
23

pmc

Project Management in Code - An incredibly straight-forward project management and build tool for Scala.
Scala
4
star
24

youi-designer

User interface designer tool to create, edit, import, export, and generate user interfaces for youi.
Scala
4
star
25

youi-template

Infrastructure for working with existing HTML files.
Scala
4
star
26

uberzip

Very fast multi-threaded unzipping utility.
Scala
3
star
27

youi-example

Example application built on YouI
Scala
3
star
28

robobrowser

Headless Browser wrapper library providing lots of features for API-access
Scala
3
star
29

hyperscala

DEPRECATED - See https://github.com/outr/youi for something far better.
Scala
3
star
30

youi-plugin

SBT plugin for use with YouI projects
Scala
3
star
31

outrbackup

Multi-threaded backup system.
Scala
2
star
32

iconsole

Web-based terminal / console with modular integration and distributed connectivity
Scala
2
star
33

batcher

Command-line tool to batch operations, pause, save, and control concurrency
Scala
2
star
34

async

Scala and Scala.js framework to execute and schedule asynchronous tasks
Scala
2
star
35

jsdoc2scalajs

Automated conversion of JSDocs to Scala.js facades.
Scala
1
star
36

webmidi.scala.js

Scala.js facade for Web MIDI API and https://github.com/cwilso/WebMIDIAPIShim
Scala
1
star
37

scalarelational-manual

Source for generating the ScalaRelational manual
Scala
1
star
38

sgine-desktop.g8

Desktop-only template for Sgine
Scala
1
star
39

geoscala

Locational data index that is full-text searchable and can update itself. Complete geospatial sorting and filtering support.
Scala
1
star
40

jar-heaven

The final solution to JAR Hell
Scala
1
star
41

smartystreets-scala-sdk

Scala SDK for SmartyStreets (https://smartystreets.com)
Scala
1
star
42

torrent

Prototype for bittorrent management in Scala
Scala
1
star
43

scalajs-fabricjs

Facade around Fabric.js for Scala.js
Scala
1
star