Skip to content

Commit 0f41722

Browse files
nodkznodkz
committed
docs: Improved README and examples.
1 parent e6c6448 commit 0f41722

File tree

4 files changed

+241
-156
lines changed

4 files changed

+241
-156
lines changed

‎README.md

Lines changed: 118 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -6,16 +6,124 @@ graphql-compose-elasticsearch
66
[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)
77
[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)
88

9-
## IN PROGRESS...
10-
Some parts are not ready yet. More features will be landed in near future.
11-
- [x] ElasticApiParser
12-
- [x] Mapping converter to GraphQL types
13-
- [x] Extended definition for `search.body` according to Query DSL
14-
- [x] Exporting of generated GraphQL field configs for Elastic methods
15-
- [ ] Improve `search.body` Query DSL by field names from provided Mapping
16-
- [ ] Helper methods/resolvers for `graphql-compose`
17-
- [ ] Docs
18-
- [ ] Declarations for output (can not find proper source/format for Elastic responses. Please open issue with a link if you have such)
9+
This module expose Elastic Search REST API via GraphQL.
10+
11+
## Elastic Search REST API proxy
12+
13+
Supported all elastic versions that support official [elasticsearch-js](https://github.com/elastic/elasticsearch-js) client. Internally it parses its source code annotations and generates all available methods with params and descriptions to GraphQL Field Config Map. You may put this config map to any GraphQL Schema.
14+
15+
```js
16+
import elasticsearch from 'elasticsearch';
17+
import { elasticApiFieldConfig } from 'graphql-compose-elasticsearch';
18+
19+
const schema = new GraphQLSchema({
20+
query: new GraphQLObjectType({
21+
name: 'Query',
22+
fields: {
23+
elastic50: elasticApiFieldConfig(
24+
// you may provide existed Elastic Client instance
25+
new elasticsearch.Client({
26+
host: 'http://localhost:9200',
27+
apiVersion: '5.0',
28+
})
29+
),
30+
31+
// or may provide just config
32+
elastic24: elasticApiFieldConfig({
33+
host: 'http://user:pass@localhost:9200',
34+
apiVersion: '2.4',
35+
}),
36+
37+
elastic17: elasticApiFieldConfig({
38+
host: 'http://user:pass@localhost:9200',
39+
apiVersion: '1.7',
40+
}),
41+
},
42+
}),
43+
});
44+
```
45+
46+
Full [code example](https://github.com/nodkz/graphql-compose-elasticsearch/tree/master/examples/differentVersions)
47+
48+
## TypeComposer from Elastic mapping
49+
In other side this module is a plugin for [graphql-compose](https://github.com/nodkz/graphql-compose), which derives GraphQLType from your [elastic mapping](https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping.html) generates input fields for all available methods in QueryDSL, Aggregations, Sorting with field autocompletion according to types in your mapping (like query dev tool in Kibana).
50+
51+
Generated TypeComposer has several awesome resolvers:
52+
- `search` - greatly simplified `search` method. According to GraphQL adaptation and its projection bunch of params setup automatically due your graphql query.
53+
- `searchConnection` - `search` method that implements Relay Cursor Connection [spec](https://facebook.github.io/relay/graphql/connections.htm) for infinite lists. Internally it uses cheap [search_after](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-search-after.html) API. One downside, Elastic does not support backward scrolling, so `before` argument will not work.
54+
- more resolvers will be later after my vacation: `suggest`, `getById`, `updateById` and others
55+
56+
```js
57+
const mapping = {
58+
properties: {
59+
name: {
60+
type: 'text',
61+
fields: {
62+
keyword: {
63+
type: 'keyword',
64+
},
65+
},
66+
},
67+
gender: {
68+
type: 'keyword',
69+
},
70+
skills: {
71+
type: 'text',
72+
},
73+
languages: {
74+
type: 'keyword',
75+
},
76+
location: {
77+
properties: {
78+
name: {
79+
type: 'text',
80+
},
81+
point: {
82+
type: 'geo_point',
83+
},
84+
},
85+
},
86+
createdAt: {
87+
type: 'date',
88+
},
89+
},
90+
};
91+
92+
const UserTC = composeWithElastic({
93+
graphqlTypeName: 'UserES',
94+
elasticIndex: 'user',
95+
elasticType: 'user',
96+
elasticMapping: mapping,
97+
elasticClient: new elasticsearch.Client({
98+
host: 'http://localhost:9200',
99+
apiVersion: '5.0',
100+
log: 'trace',
101+
}),
102+
// elastic mapping does not contain information about is fields are arrays or not
103+
// so provide this information explicitly for obtaining correct types in GraphQL
104+
pluralFields: ['skills', 'languages'],
105+
});
106+
107+
const Schema = new GraphQLSchema({
108+
query: new GraphQLObjectType({
109+
name: 'Query',
110+
fields: {
111+
user: UserTC.get('$search').getFieldConfig(),
112+
userConnection: UserTC.get('$searchConnection').getFieldConfig(),
113+
},
114+
}),
115+
});
116+
```
117+
118+
Full [code example](https://github.com/nodkz/graphql-compose-elasticsearch/blob/master/examples/elastic50/index.js)
119+
120+
## Installation
121+
```
122+
yarn add graphql graphql-compose elasticsearch graphql-compose-elasticsearch
123+
// or
124+
npm install graphql graphql-compose elasticsearch graphql-compose-elasticsearch --save
125+
```
126+
Modules `graphql`, `graphql-compose`, `elasticsearch` are in `peerDependencies`, so should be installed explicitly in your app.
19127

20128
## Live demos
21129
[Introspection of Elasticsearch API via Graphiql](https://graphql-compose.herokuapp.com/elasticsearch/)
@@ -24,7 +132,6 @@ Some parts are not ready yet. More features will be landed in near future.
24132

25133
<img width="1314" alt="screen shot 2017-03-07 at 22 34 01" src="https://cloud.githubusercontent.com/assets/1946920/23859892/65e71744-082f-11e7-8c1a-cafeb87e08e6.png">
26134

27-
<img width="423" alt="screen shot 2017-03-07 at 22 34 54" src="https://cloud.githubusercontent.com/assets/1946920/23859897/6964583c-082f-11e7-8ada-c4d2a1628a52.png">
28135

29136
## License
30137
[MIT](https://github.com/nodkz/graphql-compose-elasticsearch/blob/master/LICENSE.md)

‎examples/differentVersions/index.js

Lines changed: 17 additions & 86 deletions
Original file line numberDiff line numberDiff line change
@@ -1,92 +1,31 @@
11
import express from 'express';
22
import graphqlHTTP from 'express-graphql';
3-
import { GraphQLSchema, GraphQLObjectType, GraphQLString } from 'graphql';
4-
import elasticsearch from 'elasticsearch';
5-
import ElasticApiParser from '../../src/ElasticApiParser'; // or import { ElasticApiParser } from 'graphql-compose-elasticsearch';
3+
import { GraphQLSchema, GraphQLObjectType } from 'graphql';
4+
import { elasticApiFieldConfig } from '../../src'; // from 'graphql-compose-elasticsearch';
65

76
const expressPort = process.env.port || process.env.PORT || 9201;
87

98
const generatedSchema = new GraphQLSchema({
109
query: new GraphQLObjectType({
1110
name: 'Query',
1211
fields: {
13-
// see node_modules/elasticsearch/src/lib/apis/ for available versions
12+
elastic50: elasticApiFieldConfig({
13+
host: 'http://user:pass@localhost:9200',
14+
apiVersion: '5.0',
15+
// log: 'trace',
16+
}),
1417

15-
elastic50: {
16-
description: 'Elastic v5.0',
17-
type: new GraphQLObjectType({
18-
name: 'Elastic50',
19-
fields: new ElasticApiParser({
20-
version: '5_0',
21-
prefix: 'Elastic50',
22-
}).generateFieldMap(),
23-
}),
24-
args: {
25-
host: {
26-
type: GraphQLString,
27-
defaultValue: 'http://user:pass@localhost:9200',
28-
},
29-
},
30-
resolve: (src, args, context) => {
31-
// eslint-disable-next-line no-param-reassign
32-
context.elasticClient = new elasticsearch.Client({
33-
host: args.host,
34-
apiVersion: '5.0',
35-
log: 'trace',
36-
});
37-
return {};
38-
},
39-
},
18+
elastic24: elasticApiFieldConfig({
19+
host: 'http://user:pass@localhost:9200',
20+
apiVersion: '2.4',
21+
// log: 'trace',
22+
}),
4023

41-
elastic24: {
42-
description: 'Elastic v2.4',
43-
type: new GraphQLObjectType({
44-
name: 'Elastic24',
45-
fields: new ElasticApiParser({
46-
version: '2_4',
47-
prefix: 'Elastic24',
48-
}).generateFieldMap(),
49-
}),
50-
args: {
51-
host: {
52-
type: GraphQLString,
53-
defaultValue: 'http://user:pass@localhost:9200',
54-
},
55-
},
56-
resolve: (src, args, context) => {
57-
// eslint-disable-next-line no-param-reassign
58-
context.elasticClient = new elasticsearch.Client({
59-
host: args.host,
60-
apiVersion: '2.4',
61-
});
62-
return {};
63-
},
64-
},
65-
66-
elastic17: {
67-
description: 'Elastic v1.7',
68-
type: new GraphQLObjectType({
69-
name: 'Elastic17',
70-
fields: new ElasticApiParser({
71-
version: '5_0',
72-
prefix: 'Elastic17',
73-
}).generateFieldMap(),
74-
}),
75-
args: {
76-
host: {
77-
type: GraphQLString,
78-
defaultValue: 'http://user:pass@localhost:9200',
79-
},
80-
},
81-
resolve: (src, args, context) => {
82-
// eslint-disable-next-line no-param-reassign
83-
context.elasticClient = new elasticsearch.Client({
84-
host: args.host,
85-
apiVersion: '1.7',
86-
});
87-
return {};
88-
},
89-
},
24+
elastic17: elasticApiFieldConfig({
25+
host: 'http://user:pass@localhost:9200',
26+
apiVersion: '1.7',
27+
// log: 'trace',
28+
}),
9029
},
9130
}),
9231
});
@@ -97,14 +36,6 @@ server.use(
9736
graphqlHTTP({
9837
schema: generatedSchema,
9938
graphiql: true,
100-
context: {
101-
// // OR YOU MAY DEFINE elasticClient GLOBALLY
102-
// elasticClient: new elasticsearch.Client({
103-
// host: 'http://localhost:9200',
104-
// apiVersion: '5.0',
105-
// log: 'trace',
106-
// }),
107-
},
10839
})
10940
);
11041

0 commit comments

Comments
 (0)