Skip to content

Commit 858f571

Browse files
michaelklishinmichaelklishin
committed
Move doc guides to this repo
1 parent 30f30e9 commit 858f571

8 files changed

+2134
-15
lines changed

‎README.md

+5-15
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Neocons, a Clojure client for the Neo4J REST API
22

3-
Neocons is a feature rich idiomatic [Clojure client for the Neo4J REST API](http://clojureneo4j.info).
3+
Neocons is a feature rich idiomatic Clojure client for the Neo4J REST API.
44

55

66
## Supported Features
@@ -34,9 +34,9 @@ Neocons currently supports the following features (all via REST API, so [you can
3434

3535
## Documentation & Examples
3636

37-
To get started and see what using Neocons feels like, please use our [Getting started with Clojure and Neo4J Server](http://clojureneo4j.info/articles/getting_started.html) guide.
37+
To get started and see what using Neocons feels like, please use our [Getting started with Clojure and Neo4J Server](./docs/guides/getting_started.html) guide.
3838

39-
[Documentation guides](http://clojureneo4j.info) are mostly complete.
39+
[Documentation guides](./docs/guides/) can be found in the same repository.
4040
For more examples, see our [test suite](test).
4141

4242

@@ -49,8 +49,7 @@ To subscribe for announcements of releases, important changes and so on, please
4949

5050
## Project Maturity
5151

52-
Neocons is not a young project: first released in October 2011, it's been
53-
in production use from week 1.
52+
First released in October 2011, it's been in production use from very early on.
5453

5554
It now supports Neo4j 3.x & 2.x release(s) and the API is stable. Documentation
5655
is in good shape, too.
@@ -86,15 +85,6 @@ With Maven:
8685
</dependency>
8786

8887

89-
90-
## Continuous Integration
91-
92-
[![Continuous Integration status](https://secure.travis-ci.org/michaelklishin/neocons.png)](http://travis-ci.org/michaelklishin/neocons)
93-
94-
95-
CI is hosted by [travis-ci.org](http://travis-ci.org)
96-
97-
9888
## Supported Clojure Versions
9989

10090
Neocons requires Clojure 1.8+.
@@ -167,7 +157,7 @@ and pass the default credentials to lein on the command line
167157

168158
## License
169159

170-
Copyright (C) 2011-2018 Michael S. Klishin, Alex Petrov, and the ClojureWerkz team.
160+
Copyright (C) 2011-2024 Michael S. Klishin, Alex Petrov, and the ClojureWerkz team.
171161

172162
Double licensed under the [Eclipse Public License](http://www.eclipse.org/legal/epl-v10.html) (the same as Clojure) or
173163
the [Apache Public License 2.0](http://www.apache.org/licenses/LICENSE-2.0.html).

‎docs/guides/README.md

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Neocons Doc Guides
2+
3+
### [Getting started](./getting_started.md)
4+
5+
An overview of Neocons with a quick tutorial that helps you to get started with it. It should take about
6+
10 minutes to read and study the provided code examples
7+
8+
### [Populating the graph](./populating.md)
9+
10+
This guide covers:
11+
12+
* Creating nodes
13+
* Connecting nodes by creating relationships
14+
* Node and relationship attributes
15+
* Indexing of nodes (Legacy)
16+
* Indexing of relationships (Legacy)
17+
* Deleting nodes
18+
* Deleting relationships
19+
* Using Neo4j REST transaction API
20+
* Node Labels
21+
* Schema
22+
23+
24+
### [Traversing the graph](./traversing.md)
25+
26+
This guide covers:
27+
28+
* Graph traversals
29+
* Operations on paths
30+
* Path predicates
31+
32+
33+
### [Cypher Query Language](./cypher.md)
34+
35+
This guide covers:
36+
37+
* Using [Cypher, a query language for graphs](http://docs.neo4j.org/chunked/stable/cypher-query-lang.html)

‎docs/guides/community.md

+42
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
title: "Neocons, a Clojure client for Neo4J REST API: Community"
3+
layout: article
4+
---
5+
6+
## Mailing List
7+
8+
[Neocons has a mailing list](https://groups.google.com/forum/#!forum/clojure-neo4j). Feel free to join it and ask any questions you may have.
9+
10+
11+
## IRC
12+
13+
Feel free to stop by `#clojurewerkz` on `irc.freenode.net`. There is a [Web IRC client](http://webchat.freenode.net/)
14+
if you need one.
15+
16+
17+
## News & Announcements on Twitter
18+
19+
To subscribe for announcements of releases, important changes and so on, please follow [@ClojureWerkz](https://twitter.com/#!/clojurewerkz) on Twitter.
20+
21+
22+
## What is ClojureWerkz?
23+
24+
Neocons is part of the group of [Clojure libraries](http://clojurewerkz.org) known as ClojureWerkz, together with
25+
[Monger](http://clojuremongodb.info), [Welle](http://clojureriak.info), [Quartzite](http://clojurequartz.info), [Mailer](https://github.com/clojurewerkz/mailer), [Langohr](https://github.com/michaelklishin/langohr), [Elastisch](https://github.com/clojurewerkz/elastisch) and several others.
26+
27+
28+
## Reporting Issues
29+
30+
If you find a bug, poor default, missing feature or find any part of the API inconvenient, please [file an issue](https://github.com/michaelklishin/neocons/issues) on Github.
31+
If possible, try to explain what behavior you expected and why. Bonus points for contributing failing test cases.
32+
33+
34+
## Contributing
35+
36+
Neocons uses [Leiningen 2](https://github.com/technomancy/leiningen/blob/master/doc/TUTORIAL.md). Make sure you have it installed and then run tests against
37+
supported Clojure versions using
38+
39+
lein2 all test
40+
41+
Then create a branch and make your changes on it. Once you are done with your changes and all tests pass, submit a pull request
42+
on Github.

‎docs/guides/cypher.md

+128
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
---
2+
title: "Neocons, a Clojure client for Neo4J REST API: Using the Cypher Query Language"
3+
layout: article
4+
---
5+
6+
## About this guide
7+
8+
* What is Cypher
9+
* Using Cypher to traverse graphs, retrieve nodes, relationships and path
10+
* Using mutating Cypher in Neo4J 1.8 to create and mutate graphs
11+
12+
This work is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons Attribution 3.0 Unported License</a> (including images & stylesheets). The source is available [on Github](https://github.com/clojurewerkz/neocons.docs).
13+
14+
15+
## What version of Neocons does this guide cover?
16+
17+
This guide covers Neocons 2.0.
18+
19+
20+
## Cypher Overview
21+
22+
One of the most powerful features of Neo4J is [Cypher, a query language (like SQL) for querying, traversing and mutating (Neo4J Server 1.8+)
23+
graphs](http://docs.neo4j.org/chunked/milestone/cypher-query-lang.html). Cypher makes queries like "return me all friends of my friends" or "return me all pages this page links to that were updated
24+
less than 24 hours ago" possible in a couple of lines of code. As such, operations and ad hoc queries in the Clojure REPL or Neo4J shell
25+
with Cypher are very common.
26+
27+
Cypher also enables several operations Neo4J Server REST API does not provide to be executed efficiently. One common example is
28+
the "multi-get" operation that returns a collection of nodes by ids.
29+
30+
Cypher queries are performed using `clojurewerkz.neocons.rest.cypher/tquery` and `clojurewerkz.neocons.rest.cypher/query` functions.
31+
`clojurewerkz.neocons.rest.cypher/tquery` is more common because it returns data in a more convenient tabular form, while
32+
`/query` returns columns and result rows separately.
33+
34+
Covering Cypher itself is out of scope for this tutorial so lets just take a look at a couple of examples. Here is how
35+
to find all Amy's friends via Cypher:
36+
37+
``` clojure
38+
(ns neocons.docs.examples
39+
(:require [clojurewerkz.neocons.rest :as nr]
40+
[clojurewerkz.neocons.rest.nodes :as nn]
41+
[clojurewerkz.neocons.rest.relationships :as nrl]
42+
[clojurewerkz.neocons.rest.cypher :as cy]))
43+
44+
(defn -main
45+
[& args]
46+
(let [conn (nr/connect "http://localhost:7474/db/data/")
47+
amy (nn/create conn {:username "amy"})
48+
bob (nn/create conn {:username "bob"})
49+
_ (nrl/create conn amy bob :friend {:source "college"})
50+
res (cy/tquery conn "START person=node({sid}) MATCH person-[:friend]->friend RETURN friend" {:sid (:id amy)})]
51+
(println res)))
52+
```
53+
54+
And here is how to get back usernames and ages of multiple people using Cypher:
55+
56+
``` clojure
57+
(ns neocons.docs.examples
58+
(:require [clojurewerkz.neocons.rest :as nr]
59+
[clojurewerkz.neocons.rest.nodes :as nn]
60+
[clojurewerkz.neocons.rest.relationships :as nrl]
61+
[clojurewerkz.neocons.rest.cypher :as cy]))
62+
63+
(defn -main
64+
[& args]
65+
(let [conn (nr/connect "http://localhost:7474/db/data/")
66+
amy (nn/create conn {:username "amy" :age 27})
67+
bob (nn/create conn {:username "bob" :age 28})
68+
_ (nrl/create conn amy bob :friend {:source "college"})
69+
res (cy/tquery conn "START x = node({ids}) RETURN x.username, x.age" {:ids (map :id [amy bob])})]
70+
(println res)))
71+
```
72+
73+
The latter query is roughly equivalent to
74+
75+
``` sql
76+
SELECT username, age FROM nodes WHERE id IN (…);
77+
```
78+
79+
in SQL.
80+
81+
Cypher is fundamental to Neo4J is the most powerful (and easy to use) tool for many common cases.
82+
83+
84+
85+
## Retrieving nodes via Cypher
86+
87+
TBD
88+
89+
90+
## Retrieving relationships via Cypher
91+
92+
TBD
93+
94+
95+
## Retrieving paths via Cypher
96+
97+
TBD
98+
99+
100+
## Creating nodes via Cypher
101+
102+
TBD
103+
104+
105+
## Creating relationships via Cypher
106+
107+
TBD
108+
109+
110+
## Updating nodes via Cypher
111+
112+
TBD
113+
114+
115+
116+
## What to Read Next
117+
118+
Congratulations, this is the last guide. For the definitive reference on Cypher, see [Neo4J documentation on Cypher](http://docs.neo4j.org/chunked/stable/cypher-query-lang.html).
119+
120+
Take a look at [other guides](/articles/guides.html), they cover all kinds of topics.
121+
122+
123+
124+
## Tell Us What You Think!
125+
126+
Please take a moment to tell us what you think about this guide on Twitter or the [Neocons mailing list](https://groups.google.com/forum/#!forum/clojure-neo4j)
127+
128+
Let us know what was unclear or what has not been covered. Maybe you do not like the guide style or grammar or discover spelling mistakes. Reader feedback is key to making the documentation better.

0 commit comments

Comments
 (0)