Aspen

Simple graph data

Watch a demo
Get Aspen on Github Sponsor Aspen

What is Aspen?

Aspen is like Markdown but for graph data.
- Nobody

Aspen is a simple markup language for creating graph data.

Aspen lets you write about people, places, things, and the relationships between them using marked-up text, and converts your text to valid Cypher that can be used in Neo4j graph databases.

So, Aspen is both a markup language and a software tool that converts text to Cypher.

Aspen does not aspire to be a query language—Cypher is a truly elegant language for querying graph data, and we're frankly in awe of it. Aspen is intended to make it easy to write graph data by hand.

To learn more about Aspen, check our getting started guide in the README on Github. Or keep reading to get an overview of the language and tools.

Language Features

Simplicity

Aspen is like Coffeescript or Haml, but for Cypher.
- No one (and that's not a precise comparison, but ok)

If you need to generate data for your Neo4j graph database, writing Aspen is much simpler than writing Cypher. You can use Aspen to sketch out your data and iterate on data models, without having to think about Cypher syntax and formatting, or keeping track of matches and their nicknames.

This Aspen code: 

default Person, name
default_attribute Employer, company_name
reciprocal knows, is friends with

# Write out the narrative data
(Matt) [is friends with] (Brianna).
(Eliza) [knows] (Brianna).
(Matt) [is friends with] (Eliza).

(Matt) [works for] (Employer, UMass Boston).

produces this Cypher code: 

MERGE (person_matt:Person { name: "Matt" })
MERGE (person_brianna:Person { name: "Brianna" })
MERGE (person_eliza:Person { name: "Eliza" })
MERGE (employer_umass_boston:Employer { company_name: "UMass Boston" })

MERGE (person_matt)-[:IS_FRIENDS_WITH]-(person_brianna)
MERGE (person_eliza)-[:KNOWS]-(person_brianna)
MERGE (person_matt)-[:IS_FRIENDS_WITH]-(person_eliza)
MERGE (person_matt)-[:WORKS_FOR]->(employer_umass_boston)
;

which produces this graph:

Aspen Sample

In the small example above, Aspen requires less than two-thirds of the characters to represent the same data in Cypher, and that ratio is expected get smaller the more Aspen there is. Aspen lets you spend less time typing Cypher syntax and more time thinking about your data.

Auto-nicknaming

Cypher is an amazing query language, but when you're adding data with Cypher, you're required to keep track of matches and nicknames as you build relationships. Aspen relieves you of that extra mental load, which lets you focus on your data.

Custom grammars

that is pretty cool
- Sean Grant

Aspen aspires to let you write simply but produce rich, complicated graph data. Custom grammars enable you to write simple sentences with no markup, and map the parameters to complex Cypher statements. 

default Person, name

# Custom grammar
map
  (Person a) donated $(float amt) to (Person b).
  (Person a) gave (Person b) $(float amt).
to
  ({a})-[:GAVE_DONATION]->(:Donation { amount: {amt} })<-[:RECEIVED_DONATION]-({b})

# Narrative data
Matt donated $20 to Hélène.
Krista gave Hélène $30.75.

# Cypher generated from the above custom grammar and narrative
MERGE (person_matt:Person { name: "Matt" })
MERGE (person_helene:Person { name: "Hélène" })
MERGE (person_krista:Person { name: "Krista" })

MERGE (person_matt)-[:GAVE_DONATION]->(:Donation { amount: 20.0 })<-[:RECEIVED_DONATION]-(person_helene)
MERGE (person_krista)-[:GAVE_DONATION]->(:Donation { amount: 30.75 })<-[:RECEIVED_DONATION]-(person_helene)
;
Aspen Sample

Tooling Features

Compilation

The simplest use of the Aspen command-line interface (CLI) compiles Aspen files to Cypher. 

$ aspen compile path/to/aspen-file.aspen

Recompiling and publishing

The CLI can "watch" a file or folder of Aspen files, and either just recompile them to a .cql file, or push the data to a live Neo4j database over HTTP. 

$ aspen watch path/to/aspen-file.aspen --database=neo4j:pass@localhost:7474

Playground databases can use the drop option, which will clear out your data with every recompilation. 

$ aspen watch path/to/aspen-file.aspen --database=neo4j:pass@localhost:7474 --drop

In future versions of Aspen, we expect to support projects that compile many Aspen discourses, grammars, and narratives into one big dataset that pushes to a database.

(Coming soon) Aspen Notebook for live editing

Let's be honest: graph data is complex. Aspen syntax can only simplify things to a certain degree, so we have plans to create a live editor called Notebook. On the left side, you'll write Aspen, and on the right side, you'll see the Cypher and/or the visual graph representation of your data.

You'll be able to use Aspen Notebook to iterate on your data, and if you'd like, publish to a Neo4j instance.

Q&A

Does Aspen use Natural Language Processing (NLP)?

Aspen does not use NLP, and we don't plan to include it. The entire Aspen system is intended to be legible—there's no magic here, or even particularly complex concepts. Compared to ambitious projects like Codex that seek to convert massive amounts of variable text to graph data, Aspen is humble. For now, let's see what complexity we can manage using simple ideas and simple patterns.

Why not just import a spreadsheet?

If your data is already structured, and importing a CSV (or JSON, or other structured data) is the fastest and most obvious way to import your data, go ahead and do that. Aspen isn't built for fully-structured data, it's meant for semi-structured text that doesn't feel quite right in a spreadsheet.

Use it if it makes sense for your project, but don't force it.

Can you help me get started using Aspen?

Yes, we'd be happy to!

Since the language is in its early days and the installation process isn't what we'd like it to be, just get in touch and we'll help you get started for free.

For larger projects, we're open to contract work. If you want to see Aspen grow and mature, we're also open to sponsorship-type arrangements. Feel free to get in touch and we can talk about what makes sense for us.

Why did you create Aspen?

In late 2019, Matt (who studies conflict resolution and writes about peace) tried to quickly model the factors in a conflict in Neo4j, using Cypher. So, Aspen came out of a desire to write freeform text describing a network, and quickly visualize it.

Is there a story behind the name?

We wanted the name to reflect the branching and sometimes tree-like nature of graph data, to be short and pronounceable, and to provide good puns for naming future parts of the platform. Plus, as you can tell from Matt's Github username (@beechnut), he's a bit of a forest geography nerd. Inspired in part by forest geography and in part by the aspen grove in the indie game Firewatch, Aspen seemed like the perfect name. (P.S. The package repository for Aspen will absolutely be called the Aspen Grove.)

How can I support Aspen?

So far, Aspen has been a volunteer project, and we'd welcome your support. You can support Aspen in a few different ways.