elasticgraph-query_interceptor 1.0.0.rc3 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +71 -34
  3. metadata +16 -16
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 64892a43cd68661b2c76e524ae9090bc68b744a437079444461099411d6e13b6
4
- data.tar.gz: d315ce611120cda4761b4db050cf3c61bf4a8fb1653c92220b1df31be0b3b61a
3
+ metadata.gz: 10b6ac87b2a7efd6259d8f5b9c901b3206e675db4268dd2bd74b6200cedda1e0
4
+ data.tar.gz: 677b287a4b8d17048249232e79ddfb75dbe98f4ea11d3d3b871b0829f68980c8
5
5
  SHA512:
6
- metadata.gz: b8501921be29b4b1d90458249e8778e3c01531f2f3e6dd3c3769b8bf618c3f01910362234ce6560e6c50e3f666bbd7f0d5f4fbe46166216714ecdfbefbfe1aa5
7
- data.tar.gz: ae83c9b3ddb9a23a725ceef249fda87b2b31fb1e0536c48ca5a2070d6d88a563ac3cfa2bcdc3ce8d099b17abe8b6f5e5ac43a9f14e1fdf463d52e7e64bb6cd94
6
+ metadata.gz: 70e76307298a38c5433decf1afd516d29e5d66dd52b1ffc7490556bde7a9fc17b2839edb40d9070236fbb59baa01a0ea64b0aaa7430be0c79c21887aa8fc57ae
7
+ data.tar.gz: 2e8e9e9674aea80052ae16038469a9efe0ea4067196661ee838fba2bb70f8a965142651fb4b9c4a5da27984443c57737e9556fe7a9bb74226f338c1e772e12d7
data/README.md CHANGED
@@ -1,8 +1,12 @@
1
1
  # ElasticGraph::QueryInterceptor
2
2
 
3
- An ElasticGraph extension library that lets you intercept datastore
4
- queries before they are submitted in order to customize/modify them some
5
- how.
3
+ An ElasticGraph extension for intercepting datastore queries.
4
+
5
+ Interceptors can customize/modify datastore queries before they are submitted to Elasticsearch or OpenSearch.
6
+ Some of the use cases for query interceptors include:
7
+
8
+ * **Automatic filtering**: A query interceptor can apply default filtering to a query. For example, this can be used to automatically exclude soft-deleted/tombstoned records.
9
+ * **Query optimization**: When querying an index that uses shard routing or rollover, queries that filter on the shard routing or rollover timestamp fields are much more performant. A query interceptor can apply filters on these fields after querying a derived index for the appropriate values.
6
10
 
7
11
  ## Dependency Diagram
8
12
 
@@ -25,41 +29,74 @@ graph LR;
25
29
 
26
30
  First, add `elasticgraph-query_interceptor` to your `Gemfile`:
27
31
 
28
- ``` ruby
29
- gem "elasticgraph-query_interceptor"
30
- ```
32
+ ```diff
33
+ diff --git a/Gemfile b/Gemfile
34
+ index 4a5ef1e..5c16c2b 100644
35
+ --- a/Gemfile
36
+ +++ b/Gemfile
37
+ @@ -8,6 +8,7 @@ gem "elasticgraph-query_registry", *elasticgraph_details
31
38
 
32
- Next, configure this library in your ElasticGraph config YAML files.
33
- An optional "config" dictionary can be provided to pass in values to
34
- your interceptor when it is initialized.
39
+ # Can be elasticgraph-elasticsearch or elasticgraph-opensearch based on the datastore you want to use.
40
+ gem "elasticgraph-opensearch", *elasticgraph_details
41
+ +gem "elasticgraph-query_interceptor", *elasticgraph_details
42
+
43
+ gem "httpx", "~> 1.3"
35
44
 
36
- ``` yaml
37
- extension_modules:
38
- - require_path: elastic_graph/query_interceptor/graphql_extension
39
- name: ElasticGraph::QueryInterceptor::GraphQLExtension
40
- query_interceptor:
41
- interceptors:
42
- - require_path: ./my_app/example_interceptor
43
- name: MyApp::ExampleInterceptor
44
- config: # Optional
45
- foo: bar
46
45
  ```
47
46
 
48
- Define your interceptors at the configured paths. Each interceptor must
49
- implement this interface:
50
-
51
- ``` ruby
52
- module YourApp
53
- class ExampleInterceptor
54
- def initialize(elasticgraph_graphql:, config:)
55
- # elasticgraph_graphql is the `ElasticGraph::GraphQL` instance and has access
56
- # to things like the datastore client in case you need it in your interceptor.
57
- end
58
-
59
- def intercept(query, field:, args:, http_request:, context:)
60
- # Call `query.merge_with(...)` as desired to merge in query overrides like filters.
61
- # This method must return a query.
62
- end
47
+ Next, define the interceptor. Interceptor must implement this interface:
48
+
49
+ ```ruby
50
+ # lib/example_interceptor.rb
51
+ class ExampleInterceptor
52
+ def initialize(elasticgraph_graphql:, config:)
53
+ # `elasticgraph_graphql` is the `ElasticGraph::GraphQL` instance and has access to things like the
54
+ # datastore client in case you need it in your interceptor. This can be useful if you need to perform
55
+ # lookups on a derived index as part of your interceptor logic.
56
+ #
57
+ # `config` is a hash containing parameterized configuration values specific in the YAML settings
58
+ # (see below for an example).
59
+ end
60
+
61
+ def intercept(query, field:, args:, http_request:, context:)
62
+ # `query` is an `ElasticGraph::GraphQL::DatastoreQuery` that will be submitted to the datastore
63
+ # as part of satisfying a GraphQL query.
64
+ #
65
+ # `field`, `args`, and `context` provide access to GraphQL query information which can be used
66
+ # in your interceptor logic to influence how you modify the datastore query.
67
+ #
68
+ # `http_request` provides access to the original HTTP request and can likewise be used in your logic.
69
+ #
70
+ # Use `query.merge_with(...)` as desired to merge in query overrides like filters, or just return `query`.
71
+ # (This method must return a query.)
63
72
  end
64
73
  end
65
74
  ```
75
+
76
+ Finally, update your project's YAML config to enable this extension and configure it to use the interceptor:
77
+
78
+ ```diff
79
+ diff --git a/config/settings/local.yaml b/config/settings/local.yaml
80
+ index 963f4f9..93df6f3 100644
81
+ --- a/config/settings/local.yaml
82
+ +++ b/config/settings/local.yaml
83
+ @@ -23,6 +23,15 @@ datastore:
84
+ graphql:
85
+ default_page_size: 50
86
+ max_page_size: 500
87
+ + extension_modules:
88
+ + - require_path: elastic_graph/query_interceptor/graphql_extension
89
+ + name: ElasticGraph::QueryInterceptor::GraphQLExtension
90
+ +query_interceptor:
91
+ + interceptors:
92
+ + - require_path: ./lib/example_interceptor
93
+ + name: ExampleInterceptor
94
+ + config: # Optional
95
+ + foo: bar
96
+ logger:
97
+ device: stderr
98
+ indexer:
99
+ ```
100
+
101
+ As shown above, an optional "config" dictionary can be provided to pass in values to
102
+ your interceptor when it is initialized.
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: elasticgraph-query_interceptor
3
3
  version: !ruby/object:Gem::Version
4
- version: 1.0.0.rc3
4
+ version: 1.0.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Myron Marston
@@ -17,70 +17,70 @@ dependencies:
17
17
  requirements:
18
18
  - - '='
19
19
  - !ruby/object:Gem::Version
20
- version: 1.0.0.rc3
20
+ version: 1.0.0
21
21
  type: :runtime
22
22
  prerelease: false
23
23
  version_requirements: !ruby/object:Gem::Requirement
24
24
  requirements:
25
25
  - - '='
26
26
  - !ruby/object:Gem::Version
27
- version: 1.0.0.rc3
27
+ version: 1.0.0
28
28
  - !ruby/object:Gem::Dependency
29
29
  name: elasticgraph-schema_artifacts
30
30
  requirement: !ruby/object:Gem::Requirement
31
31
  requirements:
32
32
  - - '='
33
33
  - !ruby/object:Gem::Version
34
- version: 1.0.0.rc3
34
+ version: 1.0.0
35
35
  type: :runtime
36
36
  prerelease: false
37
37
  version_requirements: !ruby/object:Gem::Requirement
38
38
  requirements:
39
39
  - - '='
40
40
  - !ruby/object:Gem::Version
41
- version: 1.0.0.rc3
41
+ version: 1.0.0
42
42
  - !ruby/object:Gem::Dependency
43
43
  name: elasticgraph-elasticsearch
44
44
  requirement: !ruby/object:Gem::Requirement
45
45
  requirements:
46
46
  - - '='
47
47
  - !ruby/object:Gem::Version
48
- version: 1.0.0.rc3
48
+ version: 1.0.0
49
49
  type: :development
50
50
  prerelease: false
51
51
  version_requirements: !ruby/object:Gem::Requirement
52
52
  requirements:
53
53
  - - '='
54
54
  - !ruby/object:Gem::Version
55
- version: 1.0.0.rc3
55
+ version: 1.0.0
56
56
  - !ruby/object:Gem::Dependency
57
57
  name: elasticgraph-opensearch
58
58
  requirement: !ruby/object:Gem::Requirement
59
59
  requirements:
60
60
  - - '='
61
61
  - !ruby/object:Gem::Version
62
- version: 1.0.0.rc3
62
+ version: 1.0.0
63
63
  type: :development
64
64
  prerelease: false
65
65
  version_requirements: !ruby/object:Gem::Requirement
66
66
  requirements:
67
67
  - - '='
68
68
  - !ruby/object:Gem::Version
69
- version: 1.0.0.rc3
69
+ version: 1.0.0
70
70
  - !ruby/object:Gem::Dependency
71
71
  name: elasticgraph-schema_definition
72
72
  requirement: !ruby/object:Gem::Requirement
73
73
  requirements:
74
74
  - - '='
75
75
  - !ruby/object:Gem::Version
76
- version: 1.0.0.rc3
76
+ version: 1.0.0
77
77
  type: :development
78
78
  prerelease: false
79
79
  version_requirements: !ruby/object:Gem::Requirement
80
80
  requirements:
81
81
  - - '='
82
82
  - !ruby/object:Gem::Version
83
- version: 1.0.0.rc3
83
+ version: 1.0.0
84
84
  email:
85
85
  - myron@squareup.com
86
86
  executables: []
@@ -97,10 +97,10 @@ licenses:
97
97
  - MIT
98
98
  metadata:
99
99
  bug_tracker_uri: https://github.com/block/elasticgraph/issues
100
- changelog_uri: https://github.com/block/elasticgraph/releases/tag/v1.0.0.rc3
101
- documentation_uri: https://block.github.io/elasticgraph/api-docs/v1.0.0.rc3/
100
+ changelog_uri: https://github.com/block/elasticgraph/releases/tag/v1.0.0
101
+ documentation_uri: https://block.github.io/elasticgraph/api-docs/v1.0.0/
102
102
  homepage_uri: https://block.github.io/elasticgraph/
103
- source_code_uri: https://github.com/block/elasticgraph/tree/v1.0.0.rc3/elasticgraph-query_interceptor
103
+ source_code_uri: https://github.com/block/elasticgraph/tree/v1.0.0/elasticgraph-query_interceptor
104
104
  gem_category: extension
105
105
  rdoc_options: []
106
106
  require_paths:
@@ -119,7 +119,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
119
119
  - !ruby/object:Gem::Version
120
120
  version: '0'
121
121
  requirements: []
122
- rubygems_version: 3.6.7
122
+ rubygems_version: 3.6.9
123
123
  specification_version: 4
124
- summary: An ElasticGraph extension for intercepting datastore queries.
124
+ summary: Intercepts ElasticGraph datastore queries.
125
125
  test_files: []