diff --git a/about/index.html b/about/index.html
new file mode 100644
index 00000000..27a5ec81
--- /dev/null
+++ b/about/index.html
@@ -0,0 +1,113 @@
+
+
+
+
+
+
+ What is ElasticGraph?
+
+
+
+
+
+
+
+
+
+
+
+
+
What is ElasticGraph?
+
+
ElasticGraph is a general purpose, near real-time data query and search platform that is scalable and performant, serves rich interactive queries, and dramatically simplifies the creation of complex reports. The platform combines the power of indexing and search of Elasticsearch or OpenSearch with the query flexibility of GraphQL language. Optimized for AWS cloud, it also offers scale and reliability.
+
+
ElasticGraph is a naturally flexible framework with many different possible applications. However, the main motivation we have for building it is to power various data APIs, UIs and reports. These modern reports require filtering and aggregations across a body of ever growing data sets. Modern APIs allow us to:
+
+
+
Minimize network trips to retrieve your data
+
Get exactly what you want in a single query. No over- or under-serving the data.
+
Push filtering complex calculations to the backend.
+
+
+
What can I do with it?
+
+
The ElasticGraph platform will allow you to query your data in many different configurations. To do so requires defining a schema which ElasticGraph will use to both index data and also query it. Besides all basic GraphQL query features, ElasticGraph also supports:
+
+
+
Real-time indexing and data querying
+
Filtering, sorting, pagination, grouping, aggregations, and sub-aggregations
+
Navigating across data sets in a single query
+
Robust, safe schema evolution support via Query Registry mechanism
+
Derived indexes to power commonly accessed queries and aggregations
ElasticGraph extension library that implements the Apollo subgraph federation
+spec, turning
+any ElasticGraph instance into an Apollo subgraph.
+
+
ElasticGraph::Apollo has two parts:
+
+
+
SchemaDefinition is an extension used while defining an ElasticGraph schema. It includes all schema elements that are part
+of the Apollo spec, including _Entity and the various directives.
+
GraphQL is an extension used by elasticgraph-graphql to support queries against Apollo’s subgraph schema additions (e.g.
+_service and _entities). It includes reference resolvers
+for all indexed types in your schema.
+
+
+
To use elasticgraph-apollo, simply use SchemaDefinition::APIExtension as a schema definition extension module. The GraphQL
+extension module will get used by elasticgraph-graphql automatically.
This module provides no public types or APIs. It will be used automatically when you use
+SchemaDefinition::APIExtension as a schema definition extension module.
+
+
+
+
Namespace for all Apollo GraphQL enging logic.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/main/ElasticGraph/Apollo/SchemaDefinition.html b/docs/main/ElasticGraph/Apollo/SchemaDefinition.html
new file mode 100644
index 00000000..9f9ba7d7
--- /dev/null
+++ b/docs/main/ElasticGraph/Apollo/SchemaDefinition.html
@@ -0,0 +1,129 @@
+
+
+
+
+
+
+ Module: ElasticGraph::Apollo::SchemaDefinition
+
+ — Documentation by YARD 0.9.37
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Picks which version of Apollo federation to target. By default, the latest supported version is
+targeted, but you can call this to pick an earlier version, which may be necessary if your
+organization is on an older version of Apollo federation.
# File 'elasticgraph-apollo/lib/elastic_graph/apollo/schema_definition/api_extension.rb', line 101
+
+deftarget_apollo_federation_version(version)
+ # Allow the version to have the `v` prefix, but don't require it.
+version=version.delete_prefix("v")
+
+ state.apollo_directive_definitions=DIRECTIVE_DEFINITIONS_BY_FEDERATION_VERSION.fetch(version)do
+ supported_version_descriptions=DIRECTIVE_DEFINITIONS_BY_FEDERATION_VERSION.keys.mapdo|version_number|
+ "v#{version_number}"
+ end.join(", ")
+
+ raiseErrors::SchemaError,"elasticgraph-apollo v#{ElasticGraph::VERSION} does not support Apollo federation v#{version}. " \
+ "Pick one of the supported versions (#{supported_version_descriptions}) instead."
+ end
+end
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/main/ElasticGraph/Apollo/SchemaDefinition/ApolloDirectives.html b/docs/main/ElasticGraph/Apollo/SchemaDefinition/ApolloDirectives.html
new file mode 100644
index 00000000..10cafb13
--- /dev/null
+++ b/docs/main/ElasticGraph/Apollo/SchemaDefinition/ApolloDirectives.html
@@ -0,0 +1,127 @@
+
+
+
+
+
+
+ Module: ElasticGraph::Apollo::SchemaDefinition::ApolloDirectives
+
+ — Documentation by YARD 0.9.37
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Namespace for mixins that provide support for Apollo’s federation directives.
+Each Apollo federation directive is offered via an API starting with apollo. For example, apollo_key can be used to define an
+Apollo @key.
ElasticGraph automatically defines an apollo_key of id for every indexed type. This API is only needed when defining
+additional keys on an indexed type, or defining a key for a non-indexed type.
If false, indicates to the Apollo router that this subgraph doesn’t define a reference resolver for
+this entity. This means that router query plans can’t “jump to” this subgraph to resolve fields that aren’t defined in another
+subgraph.
+
+
+
+
+
+
+
+
+
+
+
+
+
+129
+130
+131
+
+
+
# File 'elasticgraph-apollo/lib/elastic_graph/apollo/schema_definition/apollo_directives.rb', line 129
+
+defapollo_key(fields:,resolvable:true)
+ directive"key",fields:fields,resolvable:resolvable
+end
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/main/ElasticGraph/Apollo/SchemaDefinition/ApolloDirectives/Override.html b/docs/main/ElasticGraph/Apollo/SchemaDefinition/ApolloDirectives/Override.html
new file mode 100644
index 00000000..3647f034
--- /dev/null
+++ b/docs/main/ElasticGraph/Apollo/SchemaDefinition/ApolloDirectives/Override.html
@@ -0,0 +1,237 @@
+
+
+
+
+
+
+ Module: ElasticGraph::Apollo::SchemaDefinition::ApolloDirectives::Override
+
+ — Documentation by YARD 0.9.37
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Calling this method on a field will cause the field and every schema element derived from the field (e.g. the filter field,
+he aggregation field, etc), to be tagged with the given tag_name, ensuring that all capabilities related to the field are
+available in the contract variant.
+
+
+
+
+
+
+
+
Examples:
+
+
+
Tag a field (and its derived elements) with “public”
+
+
+
ElasticGraph.define_schemado|schema|
+ schema.object_type"Campaign"do|t|
+ t.field"name","String"do|f|
+ f.tag_with"public"
+ end
+ end
+end
+
+
+
Parameters:
+
+
+
+
+ tag_name
+
+
+ (String)
+
+
+
+ —
+
tag to add to schema elements generated for this field
# File 'elasticgraph-apollo/lib/elastic_graph/apollo/schema_definition/field_extension.rb', line 47
+
+deftag_with(tag_name)
+ on_each_generated_schema_elementdo|element|
+ needs_tagging=
+ ifelement.is_a?(ElasticGraph::SchemaDefinition::SchemaElements::SortOrderEnumValue)
+ # Each sort order enum value is based on a full field path (e.g. `parentField_subField_furtherNestedField_ASC`).
+# We must only tag the enum if each part of the full field path is also tagged. In this example, we should only
+# tag the enum value if `parentField`, `subField`, and `furtherNestedField` are all tagged.
+element.sort_order_field_path.all?{|f|FieldExtension.tagged_with?(f,tag_name)}
+ else
+ true
+ end
+
+ ifneeds_tagging&&!FieldExtension.tagged_with?(element,tag_name)
+ (_=element).apollo_tagname:tag_name
+ end
+ end
+end
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/main/ElasticGraph/Apollo/SchemaDefinition/InputTypeExtension.html b/docs/main/ElasticGraph/Apollo/SchemaDefinition/InputTypeExtension.html
new file mode 100644
index 00000000..da75cb40
--- /dev/null
+++ b/docs/main/ElasticGraph/Apollo/SchemaDefinition/InputTypeExtension.html
@@ -0,0 +1,142 @@
+
+
+
+
+
+
+ Module: ElasticGraph::Apollo::SchemaDefinition::InputTypeExtension
+
+ — Documentation by YARD 0.9.37
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Provides a validator to validate a JSON schema definition according to the JSON schema meta schema.
+The validator is configured to validate strictly, so that non-standard JSON schema properties are disallowed,
+except for internal ElasticGraph metadata properties.
Provides a validator to validate a JSON schema definitions according to the JSON schema meta schema.
+The validator is configured to validate strictly, so that non-standard JSON schema properties are disallowed.
# File 'elasticgraph-json_schema/lib/elastic_graph/json_schema/meta_schema_validator.rb', line 52
+
+defself.load_strict_validator(overrides={})
+ # Downloaded from: https://json-schema.org/draft-07/schema
+schema=::JSON.parse(::File.read(::File.expand_path("../json_schema_draft_7_schema.json",__FILE__)))
+ schema=Support::HashUtil.deep_merge(schema,overrides)unlessoverrides.empty?
+
+ # The meta schema allows additionalProperties in nearly every place. While a JSON schema definition
+# with additional properties is considered valid, we do not intend to use any additional properties,
+# and any usage of an additional property is almost certainly a typo. So here we set
+# `with_unknown_properties_disallowed`.
+root_schema=ValidatorFactory.new(schema:schema,sanitize_pii:false)# The meta schema has no PII
+.with_unknown_properties_disallowed
+ .root_schema
+
+ Validator.new(schema:root_schema,sanitize_pii:false)
+end
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/main/ElasticGraph/JSONSchema/Validator.html b/docs/main/ElasticGraph/JSONSchema/Validator.html
new file mode 100644
index 00000000..313f71f2
--- /dev/null
+++ b/docs/main/ElasticGraph/JSONSchema/Validator.html
@@ -0,0 +1,865 @@
+
+
+
+
+
+
+ Class: ElasticGraph::JSONSchema::Validator
+
+ — Documentation by YARD 0.9.37
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
# File 'elasticgraph-json_schema/lib/elastic_graph/json_schema/validator.rb', line 19
+
+classValidator<::Data.define(:schema,:sanitize_pii)
+ # Validates the given data against the JSON schema, returning true if the data is valid.
+#
+# @param data [Object] JSON data to validate
+# @return [Boolean] true if the data is valid; false if it is invalid
+#
+# @see #validate
+# @see #validate_with_error_message
+defvalid?(data)
+ schema.valid?(data)
+ end
+
+ # Validates the given data against the JSON schema, returning an array of error objects for
+# any validation errors.
+#
+# @param data [Object] JSON data to validate
+# @return [Array<Hash<String, Object>>] validation errors; will be empty if `data` is valid
+#
+# @see #valid?
+# @see #validate_with_error_message
+defvalidate(data)
+ schema.validate(data).mapdo|error|
+ # The schemas can be very large and make the output very noisy, hiding what matters. So we remove them here.
+error.delete("root_schema")
+ error.delete("schema")
+ error
+ end
+ end
+
+ # Validates the given data against the JSON schema, returning an error message string if it is invalid.
+# The error message is intended to be usable to include in a log message or a raised error.
+#
+# @param data [Object] JSON data to validate
+# @return [nil, String] a validation error message, if the data is invalid
+#
+# @note The returned error message may contain PII unless {#sanitize_pii} has not been set.
+#
+# @see #valid?
+# @see #validate
+defvalidate_with_error_message(data)
+ errors=validate(data)
+ returniferrors.empty?
+
+ errors.each{|error|error.delete("data")}ifsanitize_pii
+
+ "Validation errors:\n\n#{errors.map{|e|::JSON.pretty_generate(e)}.join("\n\n")}"
+ end
+end
# File 'elasticgraph-json_schema/lib/elastic_graph/json_schema/validator.rb', line 19
+
+classValidator<::Data.define(:schema,:sanitize_pii)
+ # Validates the given data against the JSON schema, returning true if the data is valid.
+#
+# @param data [Object] JSON data to validate
+# @return [Boolean] true if the data is valid; false if it is invalid
+#
+# @see #validate
+# @see #validate_with_error_message
+defvalid?(data)
+ schema.valid?(data)
+ end
+
+ # Validates the given data against the JSON schema, returning an array of error objects for
+# any validation errors.
+#
+# @param data [Object] JSON data to validate
+# @return [Array<Hash<String, Object>>] validation errors; will be empty if `data` is valid
+#
+# @see #valid?
+# @see #validate_with_error_message
+defvalidate(data)
+ schema.validate(data).mapdo|error|
+ # The schemas can be very large and make the output very noisy, hiding what matters. So we remove them here.
+error.delete("root_schema")
+ error.delete("schema")
+ error
+ end
+ end
+
+ # Validates the given data against the JSON schema, returning an error message string if it is invalid.
+# The error message is intended to be usable to include in a log message or a raised error.
+#
+# @param data [Object] JSON data to validate
+# @return [nil, String] a validation error message, if the data is invalid
+#
+# @note The returned error message may contain PII unless {#sanitize_pii} has not been set.
+#
+# @see #valid?
+# @see #validate
+defvalidate_with_error_message(data)
+ errors=validate(data)
+ returniferrors.empty?
+
+ errors.each{|error|error.delete("data")}ifsanitize_pii
+
+ "Validation errors:\n\n#{errors.map{|e|::JSON.pretty_generate(e)}.join("\n\n")}"
+ end
+end
+
+
+
+
+
+
+
+
+
+
Instance Method Details
+
+
+
+
+
+ #valid?(data) ⇒ Boolean
+
+
+
+
+
+
+
+
Validates the given data against the JSON schema, returning true if the data is valid.
# File 'elasticgraph-json_schema/lib/elastic_graph/json_schema/validator.rb', line 39
+
+defvalidate(data)
+ schema.validate(data).mapdo|error|
+ # The schemas can be very large and make the output very noisy, hiding what matters. So we remove them here.
+error.delete("root_schema")
+ error.delete("schema")
+ error
+ end
+end
The returned error message may contain PII unless #sanitize_pii has not been set.
+
+
+
+
Validates the given data against the JSON schema, returning an error message string if it is invalid.
+The error message is intended to be usable to include in a log message or a raised error.
+
+
+
+
+
+
Parameters:
+
+
+
+
+ data
+
+
+ (Object)
+
+
+
+ —
+
JSON data to validate
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (nil, String)
+
+
+
+ —
+
a validation error message, if the data is invalid
# File 'elasticgraph-json_schema/lib/elastic_graph/json_schema/validator_factory.rb', line 22
+
+definitialize(schema:,sanitize_pii:)
+ @raw_schema=schema
+ @root_schema=::JSONSchemer.schema(
+ schema,
+ meta_schema:schema.fetch("$schema"),
+ # Here we opt to have regular expressions resolved using an ecmo-compatible resolver, instead of Ruby's.
+#
+# We do this because regexp patterns in our JSON schema are intended to be used by JSON schema libraries
+# in many languages, not just in Ruby, and we want to support the widest compatibility. For example,
+# Ruby requires that we use `\A` and `\z` to anchor the start and end of the string (`^` and `$` anchor the
+# start and end of a line instead), where as ecmo regexes treat `^` and `$` as the start and end of the string.
+# For a pattern to be usable by non-Ruby publishers, we need to use `^/`$` for our start/end anchors, and we
+# want our validator to treat it the same way here.
+#
+# Also, this was the default before json_schemer 1.0 (and we used 0.x versions for a long time...).
+# This maintains the historical behavior we've had.
+#
+# For more info:
+# https://github.com/davishmcclurg/json_schemer/blob/v1.0.0/CHANGELOG.md#breaking-changes
+regexp_resolver:"ecma"
+ )
+
+ @sanitize_pii=sanitize_pii
+ @validators_by_type_name=::Hash.newdo|hash,key|
+ hash[key]=Validator.new(
+ schema:root_schema.ref("#/$defs/#{key}"),
+ sanitize_pii:sanitize_pii
+ )
+ end
+end
Returns a new factory configured to disallow unknown properties. By default, JSON schema
+allows unknown properties (they’ll simply be ignored when validating a JSON document). It
+can be useful to validate more strictly, so that a document with properties not defined in
+the JSON schema gets validation errors.
Whether or not to enforce the requirement that the JSON schema version is incremented every time dumping the JSON schemas results in a changed artifact.
path to the Ruby schema definition file–either the only file that defines the schema
+(using ElasticGraph.define_schema) or the “main” schema definition file, which loads other files which further define parts of
+the schema.
Overrides for the naming formats used by ElasticGraph for derived GraphQL type names. For example, to use Metrics instead of
+AggregatedValues as the suffix for the generated types supporting getting aggregated metrid values, set to
+{AggregatedValues: "%{base}Metrics"}. See SchemaDefinition::SchemaElements::TypeNamer::DEFAULT_FORMATS for the available
+formats.
+
+
Defaults to an empty hash.
+
+
+
+
+
+
+
+
Examples:
+
+
+
Change the AggregatedValues type suffix to Metrics
List of Elasticsearch versions you want to be able to boot. Rake tasks will be defined for each version to support booting and
+halting Elasticsearch locally. Defaults to the versions of Elasticsearch that are exercised by the ElasticGraph test suite, as
+defined by lib/elastic_graph/local/tested_datastore_versions.yaml:
+
+
# This file determines the versions the ElasticGraph CI build tests against, and is also # used to provide the default versions offered by the `elasticgraph-local` rake tasks. elasticsearch: - 8.15.1 # latest version as of 2024-09-06. opensearch: - 2.16.0 # latest version as of 2024-09-06. - 2.7.0 # lowest version ElasticGraph currently supports
+
+
+
+
+
+
+
+
Examples:
+
+
+
Disable Elasticsearch tasks for a project that uses OpenSearch
Generally speaking, you will want this to be true for any ElasticGraph application that is in
+production as the versioning of JSON schemas is what supports safe schema evolution as it allows
+ElasticGraph to identify which version of the JSON schema the publishing system was operating on
+when it published an event.
+
+
It can be useful to set it to false before your application is in production, as you do not want
+to be forced to bump the version after every single schema change while you are building an initial
+prototype.
+
+
+
+
Whether or not to enforce the requirement that the JSON schema version is incremented every time
+dumping the JSON schemas results in a changed artifact. Defaults to true.
+
+
+
+
+
+
+
+
Examples:
+
+
+
Disable enforcement during initial prototyping
+
+
+
ElasticGraph::Local::RakeTasks.new(
+ local_config_yaml:"config/settings/local.yaml",
+ path_to_schema:"config/schema.rb"
+)do|tasks|
+ # TODO: remove this once we're past the prototyping stage
+tasks.enforce_json_schema_version=false
+end
+
+
+
+
Returns:
+
+
+
+
+
+ (Boolean)
+
+
+
+ —
+
whether to require json_schema_version to be incremented on changes that impact json_schemas.yaml
Overrides for the names of specific GraphQL enum values for specific enum types. For example, to rename the DayOfWeek.MONDAY
+enum to DayOfWeek.MON, set to {DayOfWeek: {MONDAY: "MON"}}.
When booting Elasticsearch/OpenSearch, Kibana (or its OpenSearch equivalent, “OpenSearch Dashboards”) will also get booted,
+selecting the port by adding 10000 to the configured port.
+
+
+
+
Hash mapping environments (e.g. :test, :dev, etc) to port numbers for use when booting Elasticsearch or OpenSearch. The hash
+automatically includes an entry for the :local environment, using a port number extracted from local_config_yaml.
+
+
+
+
+
+
+
+
Examples:
+
+
+
Define what port to use to boot the datastore for the :test environment
# File 'elasticgraph-local/lib/elastic_graph/local/rake_tasks.rb', line 298
+
+defenv_port_mapping
+ @env_port_mapping
+end
+
+
+
+
+
+
+
+
+
+
+ #index_document_sizes ⇒ Boolean
+
+
+
+
+
+
+
+
+
+ Note:
+
Enabling this requires the mapper-size plugin
+to be installed on your datastore cluster. You are responsible for ensuring that is installed if you enable this feature. If you
+enable this and the plugin is not installed, you will get errors!
+
+
+
+
When enabled, ElasticGraph will configure the index mappings so that the datastore indexes a _size field in each index document.
+ElasticGraph itself does not do anything with this field, but it will be available for your use in any direct queries (e.g. via
+Kibana).
List of OpenSearch versions you want to be able to boot. Rake tasks will be defined for each version to support booting and
+halting OpenSearch locally. Defaults to the versions of OpenSearch that are exercised by the ElasticGraph test suite, as
+defined by lib/elastic_graph/local/tested_datastore_versions.yaml:
+
+
# This file determines the versions the ElasticGraph CI build tests against, and is also # used to provide the default versions offered by the `elasticgraph-local` rake tasks. elasticsearch: - 8.15.1 # latest version as of 2024-09-06. opensearch: - 2.16.0 # latest version as of 2024-09-06. - 2.7.0 # lowest version ElasticGraph currently supports
+
+
+
+
+
+
+
+
Examples:
+
+
+
Disable OpenSearch tasks for a project that uses Elasticsearch
Extension that defines a @since directive and offers a since API on fields
+
+
+
moduleSinceExtension
+ # `self.extended` is a standard Ruby hook that gets called when a module is extended onto an object.
+# The argument is the object the module was extended onto (a `SchemaDefinition::API` instance in this case).
+defself.extended(api)
+ # Define our `@since` directive
+api.raw_sdl"directive @since(date: Date!) on FIELD_DEFINITION"
+
+ # In order to hook into fields, extend the `SchemaDefinition::Factory` with a module. The factory is used
+# for creation of all schema definition objects.
+api.factory.extendFactoryExtension
+ end
+
+ moduleFactoryExtension
+ # Hook into the creation of all `SchemaDefinition::Field` objects so that we can extend each field
+# instance with our `FieldExtension` module.
+defnew_field(*args,**options)
+ super(*args,**options)do|field|
+ field.extendFieldExtension
+ yieldfieldifblock_given?
+ end
+ end
+ end
+
+ # Offer a `f.since date` API on fields.
+moduleFieldExtension
+ defsince(date)
+ directive"since",date:date
+ end
+ end
+end
+
+ElasticGraph::Local::RakeTasks.new(
+ local_config_yaml:"config/settings/local.yaml",
+ path_to_schema:"config/schema.rb"
+)do|tasks|
+ tasks.schema_definition_extension_modules=[SinceExtension]
+end
+
+
+
+
Returns:
+
+
+
+
+
+ (Array<Module>)
+
+
+
+ —
+
list of extension modules
+
+
+
+
+
+
+
+
+
+
+
+
+212
+213
+214
+
+
+
# File 'elasticgraph-local/lib/elastic_graph/local/rake_tasks.rb', line 212
+
+defschema_definition_extension_modules
+ @schema_definition_extension_modules
+end
The form of names for schema elements (fields, arguments, directives) generated by ElasticGraph, either :snake_case or
+:camelCase. For example, if set to :camelCase, ElasticGraph will generate a groupedBy field, but if set to :snake_case,
+ElasticGraph will generate a grouped_by field.
+
+
Defaults to :camelCase since most GraphQL schemas use that casing.
Overrides for specific names of schema elements (fields, arguments, directives) generated by ElasticGraph. For example, to rename
+the gt filter field to greaterThan, set to {gt: "greaterThan"}.
+
+
Defaults to an empty hash.
+
+
+
+
+
+
+
+
Examples:
+
+
+
Spell out comparison operators instead of using shortened forms
Adapts an ElasticGraph GraphQL endpoint to run as a Rack application.
+This allows an ElasticGraph GraphQL endpoint to run inside any Rack-compatible web
+framework, including Ruby on Rails,
+or as a stand-alone application. Two configurations are supported:
A simple Rack wrapper around an ElasticGraph GraphQL endpoint.
+This can be used for local development, mounted in a Rails application,
+or run in any other Rack-compatible context.
+
+
+
+
+
+
+
+
Examples:
+
+
+
Simple config.ru to run an ElasticGraph endpoint as a Rack application
A Rack application that serves both an ElasticGraph GraphQL endpoint
+and a GraphiQL IDE. This can be used for local development,
+mounted in a Rails application, or run in any other Rack-compatible context.
+
+
+
+
+
+
+
+
Examples:
+
+
+
Simple config.ru to run GraphiQL as a Rack application, targeting an ElasticGraph endpoint
Returns object responsible for instantiating all schema element classes.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Factory)
+
+
+
+ —
+
object responsible for instantiating all schema element classes
+
+
+
+
+
+
+
+
+
+
+
+
+51
+52
+53
+
+
+
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/api.rb', line 51
+
+deffactory
+ @factory
+end
+
+
+
+
+
+
+
+
+
+
+ #state ⇒ State(readonly)
+
+
+
+
+
+
+
+
Returns object which holds all state for the schema definition.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (State)
+
+
+
+ —
+
object which holds all state for the schema definition
+
+
+
+
+
+
+
+
+
+
+
+
+48
+49
+50
+
+
+
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/api.rb', line 48
+
+defstate
+ @state
+end
+
+
+
+
+
+
+
+
+
+
Instance Method Details
+
+
+
+
+
+ #deleted_type(name) ⇒ void
+
+
+
+
+
+
+
+
+
+ Note:
+
In situations where this API applies, ElasticGraph will give you an error message indicating that you need to use this API
+or SchemaElements::TypeWithSubfields#renamed_from. Likewise, when ElasticGraph no longer needs to know about this, it’ll give you a warning
+indicating the call to this method can be removed.
+
+
+
+
This method returns an undefined value.
Registers the name of a type that existed in a prior version of the schema but has been deleted.
Defines a GraphQL enum type.
+The type is restricted to an enumerated set of values, each with a unique name.
+Use value or values to define the enum values in the passed block.
+
+
Note: if required by your configuration, this may generate a pair of Enum types (an input
+enum and an output enum).
+
+
+
+
+
+
+
+
Examples:
+
+
+
Define an enum type
+
+
+
ElasticGraph.define_schemado|schema|
+ schema.enum_type"Currency"do|t|
+ t.value"USD"do|v|
+ v.documentation"US Dollars."
+ end
+
+ t.value"JPY"do|v|
+ v.documentation"Japanese Yen."
+ end
+
+ # You can define multiple values in one call if you don't care about their docs or directives.
+t.values"GBP","AUD"
+ end
+end
While this is an important part of how ElasticGraph is designed to support schema evolution, it can be annoying constantly
+have to increment this while rapidly changing the schema during prototyping. You can disable the requirement to increment this
+on every JSON schema change by setting enforce_json_schema_version to false in your Rakefile.
+
+
+
+
This method returns an undefined value.
Defines the version number of the current JSON schema. Importantly, every time a change is made that impacts the JSON schema
+artifact, the version number must be incremented to ensure that each different version of the JSON schema is identified by a unique
+version number. The publisher will then include this version number in published events to identify the version of the schema it
+was using. This avoids the need to deploy the publisher and ElasticGraph indexer at the same time to keep them in sync.
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/api.rb', line 315
+
+defjson_schema_version(version)
+ if!version.is_a?(Integer)||version<1
+ raiseErrors::SchemaError,"`json_schema_version` must be a positive integer. Specified version: #{version}"
+ end
+
+ if@state.json_schema_version
+ raiseErrors::SchemaError,"`json_schema_version` can only be set once on a schema. Previously-set version: #{@state.json_schema_version}"
+ end
+
+ @state.json_schema_version=version
+ @state.json_schema_version_setter_location=caller_locations(1,1).to_a.first
+ nil
+end
Defines a GraphQL object type Use it to define a concrete type that
+has subfields. Object types can either be indexed (e.g. directly indexed in the datastore, and available to query from the
+root Query object) or embedded in other indexed types.
+
+
+
+
+
+
+
+
Examples:
+
+
+
Define embedded and indexed object types
+
+
+
ElasticGraph.define_schemado|schema|
+ # `Money` is an embedded object type
+schema.object_type"Money"do|t|
+ t.field"currency","String"
+ t.field"amount","JsonSafeLong"
+ end
+
+ # `Transaction` is an indexed object type
+schema.object_type"Transaction"do|t|
+ t.root_query_fieldsplural:"transactions"
+ t.field"id","ID"
+ t.field"cost","Money"
+ t.index"transactions"
+ end
+end
Registers a customization callback that will be applied to every built-in type automatically provided by ElasticGraph. Provides
+an opportunity to customize the built-in types (e.g. to add directives to them or whatever).
+
+
+
+
+
+
+
+
Examples:
+
+
+
Customize documentation of built-in types
+
+
+
ElasticGraph.define_schemado|schema|
+ schema.on_built_in_typesdo|type|
+ type.append_to_documentation"This is a built-in ElasticGraph type."
+ end
+end
Defines a raw GraphQL SDL snippet that will be included in the generated schema.graphql artifact. Designed to be an escape hatch,
+for when ElasticGraph doesn’t provide another way to write some type of GraphQL SDL element that you need. Currently, the only
+known use case is to define custom GraphQL directives.
+
+
+
+
+
+
+
+
Examples:
+
+
+
Define a custom directive and use it
+
+
+
ElasticGraph.define_schemado|schema|
+ # Define a directive we can use to annotate what system a data type comes from.
+schema.raw_sdl"directive @sourcedFrom(system: String!) on OBJECT"
+
+ schema.object_type"Transaction"do|t|
+ t.directive"sourcedFrom",system:"transaction-processor"
+ end
+end
Registers a GraphQL extension module that will be loaded and used by elasticgraph-graphql. While such
+extension modules can also be configured in a settings YAML file, it can be useful to register it here
+when you want to ensure that the extension is used in all environments. For example, an extension library
+that defines custom schema elements (such as elasticgraph-apollo) may need to ensure its corresponding
+GraphQL extension module is used since the custom schema elements would not work correctly otherwise.
Defines a GraphQL scalar type. ElasticGraph itself uses this to define a few
+common scalar types (e.g. Date and DateTime), but it is also available to you to use to define your own custom scalar types.
+
+
+
+
+
+
+
+
Examples:
+
+
+
Define a scalar type
+
+
+
ElasticGraph.define_schemado|schema|
+ schema.scalar_type"URL"do|t|
+ t.mappingtype:"keyword"
+ t.json_schematype:"string",format:"uri"
+ end
+end
Defines a GraphQL union type. Use it to define an abstract supertype with one or
+more concrete subtypes. Each subtype must be an SchemaElements::ObjectType, but they do not have to share any fields in common.
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
Returns painless functions required by append_only_set.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Array<String>)
+
+
+
+ —
+
painless functions required by append_only_set.
+
+
+
+
+
+
+
+
+
+
+
+
+23
+24
+25
+
+
+
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/indexing/derived_fields/append_only_set.rb', line 23
+
+deffunction_definitions
+ [IDEMPOTENTLY_INSERT_VALUES,IDEMPOTENTLY_INSERT_VALUE]
+end
+
+
+
+
+
+
+
+
+ #setup_statements ⇒ Array<String>
+
+
+
+
+
+
+
+
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
The statements here initialize the field to an empty list if it is null. This primarily happens when the document
+does not already exist, but can also happen when we add a new derived field to an existing type.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Array<String>)
+
+
+
+ —
+
a list of painless statements that must be called at the top of the script to set things up.
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/indexing/derived_fields/field_initializer_support.rb', line 27
+
+defself.build_empty_value_initializers(destination_field,leaf_value:)
+ snippets=[]# : ::Array[::String]
+path_so_far=[]# : ::Array[::String]
+
+ destination_field.split(".").eachdo|path_part|
+ path_to_this_part=(path_so_far+[path_part]).join(".")
+ is_leaf=path_to_this_part==destination_field
+
+ unlessis_leaf&&leaf_value==:leave_unset
+ # The empty value of all parent fields must be an empty painless map, but for a leaf field it can be different.
+empty_value=is_leaf?leaf_value:EMPTY_PAINLESS_MAP
+
+ snippets<<default_source_field_to_empty(path_to_this_part,empty_value.to_s)
+ path_so_far<<path_part
+ end
+ end
+
+ snippets
+end
Derive a Course type from StudentCourseEnrollment events
+
+
+
ElasticGraph.define_schemado|schema|
+ # `StudentCourseEnrollment` is a directly indexed type.
+schema.object_type"StudentCourseEnrollment"do|t|
+ t.field"id","ID"
+ t.field"courseId","ID"
+ t.field"courseName","String"
+ t.field"studentName","String"
+ t.field"courseStartDate","Date"
+
+ t.index"student_course_enrollments"
+
+ # Here we define how the `Course` indexed type is derived when we index `StudentCourseEnrollment` events.
+t.derive_indexed_type_fields"Course",from_id:"courseId"do|derive|
+ # `derive` is an instance of `DerivedIndexedType`.
+derive.immutable_value"name",from:"courseName"
+ derive.append_only_set"students",from:"studentName"
+ derive.min_value"firstOfferedDate",from:"courseStartDate"
+ derive.max_value"mostRecentlyOfferedDate",from:"courseStartDate"
+ end
+ end
+
+ # `Course` is an indexed type that is derived entirely from `StudentCourseEnrollment` events.
+schema.object_type"Course"do|t|
+ t.field"id","ID"
+ t.field"name","String"
+ t.field"students","[String!]!"
+ t.field"firstOfferedDate","Date"
+ t.field"mostRecentlyOfferedDate","Date"
+
+ t.index"courses"
+ end
+end
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/indexing/derived_indexed_type.rb', line 67
+
+classDerivedIndexedType<::Struct.new(
+ :source_type,
+ :destination_type_ref,
+ :id_source,
+ :routing_value_source,
+ :rollover_timestamp_value_source,
+ :fields
+)
+ # @param source_type [SchemaElements::ObjectType] the type used as a source for this derive type
+# @param destination_type_ref [SchemaElements::TypeReference] the derived type
+# @param id_source [String] path to field on the source type used as `id` on the derived type
+# @param routing_value_source [String, nil] path to field on the source type used for shard routing
+# @param rollover_timestamp_value_source [String, nil] path to field on the source type used as the timestamp field for rollover
+# @yield [DerivedIndexedType] the `DerivedIndexedType` instance
+# @api private
+definitialize(
+ source_type:,
+ destination_type_ref:,
+ id_source:,
+ routing_value_source:,
+ rollover_timestamp_value_source:
+ )
+ fields=[]# : ::Array[_DerivedField]
+super(
+ source_type:source_type,
+ destination_type_ref:destination_type_ref,
+ id_source:id_source,
+ routing_value_source:routing_value_source,
+ rollover_timestamp_value_source:rollover_timestamp_value_source,
+ fields:fields
+ )
+ yieldself
+ end
+
+ # Configures `field_name` (on the derived indexing type) to contain the set union of all values from
+# the `from` field on the source type. Values are only ever appended to the set, so the field will
+# act as an append-only set.
+#
+# @param field_name [String] name of field on the derived indexing type to store the derived set
+# @param from [String] path to field on the source type to source values from
+# @return [DerivedIndexedType::AppendOnlySet]
+#
+# @example
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "StudentCourseEnrollment" do |t|
+# t.field "id", "ID"
+# t.field "courseId", "ID"
+# t.field "studentName", "String"
+#
+# t.index "student_course_enrollments"
+#
+# t.derive_indexed_type_fields "Course", from_id: "courseId" do |derive|
+# derive.append_only_set "students", from: "studentName"
+# end
+# end
+#
+# schema.object_type "Course" do |t|
+# t.field "id", "ID"
+# t.field "students", "[String!]!"
+#
+# t.index "courses"
+# end
+# end
+defappend_only_set(field_name,from:)
+ fields<<DerivedFields::AppendOnlySet.new(field_name,from)
+ end
+
+ # Configures `field_name` (on the derived indexing type) to contain a single immutable value from the
+# `from` field on the source type. Immutability is enforced by triggering an indexing failure with a
+# clear error if any event's source value is different from the value already indexed on this field.
+#
+# @param field_name [String] name of field on the derived indexing type to store the derived value
+# @param from [String] path to field on the source type to source values from
+# @param nullable [Boolean] whether the field is allowed to be set to `null`. When set to false, events
+# that contain a `null` value in the `from` field will be rejected instead of setting the field’s value
+# to `null`.
+# @param can_change_from_null [Boolean] whether a one-time mutation of the field value is allowed from
+# `null` to a non-`null` value. This can be useful when dealing with a field that may not have a value
+# on all source events. For example, if the source field was not initially part of the schema of your
+# source dataset, you may have old records that lack a value for this field. When set, this option
+# allows a one-time mutation of the field value from `null` to a non-`null` value. Once set to a
+# non-`null` value, any additional `null` values that are encountered will be ignored (ensuring that
+# the indexed data converges on the same state regardless of the order the events are ingested in).
+# Note: this option cannot be enabled when `nullable: false` has been set.
+# @return [DerivedFields::ImmutableValue]
+#
+# @example
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "StudentCourseEnrollment" do |t|
+# t.field "id", "ID"
+# t.field "courseId", "ID"
+# t.field "courseName", "String"
+#
+# t.index "student_course_enrollments"
+#
+# t.derive_indexed_type_fields "Course", from_id: "courseId" do |derive|
+# derive.immutable_value "name", from: "courseName"
+# end
+# end
+#
+# schema.object_type "Course" do |t|
+# t.field "id", "ID"
+# t.field "name", "String"
+#
+# t.index "courses"
+# end
+# end
+defimmutable_value(field_name,from:,nullable:true,can_change_from_null:false)
+ if!nullable&&can_change_from_null
+ raiseErrors::SchemaError,"`can_change_from_null: true` is not allowed with `nullable: false` (as there would be no `null` values to change from)."
+ end
+
+ fields<<DerivedFields::ImmutableValue.new(
+ destination_field:field_name,
+ source_field:from,
+ nullable:nullable,
+ can_change_from_null:can_change_from_null
+ )
+ end
+
+ # Configures `field_name` (on the derived indexing type) to contain the minimum of all values from the `from`
+# field on the source type.
+#
+# @param field_name [String] name of field on the derived indexing type to store the derived value
+# @param from [String] path to field on the source type to source values from
+# @return [DerivedIndexedType::MinOrMaxValue]
+#
+# @example
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "StudentCourseEnrollment" do |t|
+# t.field "id", "ID"
+# t.field "courseId", "ID"
+# t.field "courseStartDate", "Date"
+#
+# t.index "student_course_enrollments"
+#
+# t.derive_indexed_type_fields "Course", from_id: "courseId" do |derive|
+# derive.min_value "firstOfferedDate", from: "courseStartDate"
+# end
+# end
+#
+# schema.object_type "Course" do |t|
+# t.field "id", "ID"
+# t.field "firstOfferedDate", "Date"
+#
+# t.index "courses"
+# end
+# end
+defmin_value(field_name,from:)
+ fields<<DerivedFields::MinOrMaxValue.new(field_name,from,:min)
+ end
+
+ # Configures `field_name` (on the derived indexing type) to contain the maximum of all values from the `from`
+# field on the source type.
+#
+# @param field_name [String] name of field on the derived indexing type to store the derived value
+# @param from [String] path to field on the source type to source values from
+# @return [DerivedIndexedType::MinOrMaxValue]
+#
+# @example
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "StudentCourseEnrollment" do |t|
+# t.field "id", "ID"
+# t.field "courseId", "ID"
+# t.field "courseStartDate", "Date"
+#
+# t.index "student_course_enrollments"
+#
+# t.derive_indexed_type_fields "Course", from_id: "courseId" do |derive|
+# derive.max_value "mostRecentlyOfferedDate", from: "courseStartDate"
+# end
+# end
+#
+# schema.object_type "Course" do |t|
+# t.field "id", "ID"
+# t.field "mostRecentlyOfferedDate", "Date"
+#
+# t.index "courses"
+# end
+# end
+defmax_value(field_name,from:)
+ fields<<DerivedFields::MinOrMaxValue.new(field_name,from,:max)
+ end
+
+ # @return [Scripting::Script] Painless script that will maintain the derived fields
+# @api private
+defpainless_script
+ Scripting::Script.new(
+ source:generate_script.strip,
+ name:"#{destination_type_ref}_from_#{source_type.name}",
+ language:"painless",
+ context:"update"
+ )
+ end
+
+ # @return [SchemaArtifacts::RuntimeMetadata::UpdateTarget] runtime metadata for the source type
+# @api private
+defruntime_metadata_for_source_type
+ SchemaArtifacts::RuntimeMetadata::UpdateTarget.new(
+ type:destination_type_ref.name,
+ relationship:nil,
+ script_id:painless_script.id,
+ id_source:id_source,
+ routing_value_source:routing_value_source,
+ rollover_timestamp_value_source:rollover_timestamp_value_source,
+ metadata_params:{},
+ data_params:fields.map(&:source_field).to_hdo|f|
+ [f,SchemaArtifacts::RuntimeMetadata::DynamicParam.new(source_path:f,cardinality::many)]
+ end
+ )
+ end
+
+ private
+
+ defgenerate_script
+ iffields.empty?
+ raiseErrors::SchemaError,"`derive_indexed_type_fields` definition for #{destination_type_ref} (from #{source_type.name}) " \
+ "has no derived field definitions."
+ end
+
+ sorted_fields=fields.sort_by(&:destination_field)
+
+ # We use `uniq` here to avoid re-doing the same setup multiple times, since multiple fields can sometimes
+# need the same setup (such as initializing a common parent field to an empty map).
+function_defs=sorted_fields.flat_map(&:function_definitions).uniq.map(&:strip).sort
+
+ setup_statements=[STATIC_SETUP_STATEMENTS]+sorted_fields.flat_map(&:setup_statements).uniq.map(&:strip)
+
+ apply_update_statements=sorted_fields.map{|f|apply_update_statement(f).strip}
+
+ # Note: comments in the script are effectively "free" since:
+#
+# - The compiler will strip them out.
+# - We only send the script to the datastore once (when configuring the cluster), and later
+# reference it only by id--so we don't pay for the larger payload on each indexing request.
+<<~EOS
+#{function_defs.join("\n\n")}
+
+#{setup_statements.join("\n")}
+
+#{apply_update_statements.join("\n")}
+
+ if (!#{SCRIPT_ERRORS_VAR}.isEmpty()) {
+ throw new IllegalArgumentException("#{DERIVED_INDEX_FAILURE_MESSAGE_PREAMBLE}: " + #{SCRIPT_ERRORS_VAR}.join(" "));
+ }
+
+ // For records with no new values to index, only skip the update if the document itself doesn't already exist.
+ // Otherwise create an (empty) document to reflect the fact that the id has been seen.
+ if (ctx._source.id != null && #{sorted_fields.map{|f|was_noop_variable(f)}.join(" && ")}) {
+ ctx.op = 'none';
+ } else {
+ // Here we set `_source.id` because if we don't, it'll never be set, making these docs subtly
+ // different from docs indexed the normal way.
+ //
+ // Note also that we MUST use `params.id` instead of `ctx._id`. The latter works on an update
+ // of an existing document, but is unavailable when we are inserting the document for the first time.
+ ctx._source.id = params.id;
+ }
+ EOS
+end
+
+ defapply_update_statement(field)
+ "boolean #{was_noop_variable(field)} = !#{field.apply_operation_returning_update_status};"
+ end
+
+ defwas_noop_variable(field)
+ "#{field.destination_field.gsub(".","__")}_was_noop"
+ end
+
+ SCRIPT_ERRORS_VAR="scriptErrors"
+
+ STATIC_SETUP_STATEMENTS=<<~EOS.strip
+ Map data = params.data;
+ // A variable to accumulate script errors so that we can surface _all_ issues and not just the first.
+ List #{SCRIPT_ERRORS_VAR} = new ArrayList();
+ EOS
+end
+
+
+
+
+
+
+
+
+
+
+ #id_source ⇒ String
+
+
+
+
+
+
+
+
Returns path to field on the source type used as id on the derived type.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String)
+
+
+
+ —
+
path to field on the source type used as id on the derived type
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/indexing/derived_indexed_type.rb', line 67
+
+classDerivedIndexedType<::Struct.new(
+ :source_type,
+ :destination_type_ref,
+ :id_source,
+ :routing_value_source,
+ :rollover_timestamp_value_source,
+ :fields
+)
+ # @param source_type [SchemaElements::ObjectType] the type used as a source for this derive type
+# @param destination_type_ref [SchemaElements::TypeReference] the derived type
+# @param id_source [String] path to field on the source type used as `id` on the derived type
+# @param routing_value_source [String, nil] path to field on the source type used for shard routing
+# @param rollover_timestamp_value_source [String, nil] path to field on the source type used as the timestamp field for rollover
+# @yield [DerivedIndexedType] the `DerivedIndexedType` instance
+# @api private
+definitialize(
+ source_type:,
+ destination_type_ref:,
+ id_source:,
+ routing_value_source:,
+ rollover_timestamp_value_source:
+ )
+ fields=[]# : ::Array[_DerivedField]
+super(
+ source_type:source_type,
+ destination_type_ref:destination_type_ref,
+ id_source:id_source,
+ routing_value_source:routing_value_source,
+ rollover_timestamp_value_source:rollover_timestamp_value_source,
+ fields:fields
+ )
+ yieldself
+ end
+
+ # Configures `field_name` (on the derived indexing type) to contain the set union of all values from
+# the `from` field on the source type. Values are only ever appended to the set, so the field will
+# act as an append-only set.
+#
+# @param field_name [String] name of field on the derived indexing type to store the derived set
+# @param from [String] path to field on the source type to source values from
+# @return [DerivedIndexedType::AppendOnlySet]
+#
+# @example
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "StudentCourseEnrollment" do |t|
+# t.field "id", "ID"
+# t.field "courseId", "ID"
+# t.field "studentName", "String"
+#
+# t.index "student_course_enrollments"
+#
+# t.derive_indexed_type_fields "Course", from_id: "courseId" do |derive|
+# derive.append_only_set "students", from: "studentName"
+# end
+# end
+#
+# schema.object_type "Course" do |t|
+# t.field "id", "ID"
+# t.field "students", "[String!]!"
+#
+# t.index "courses"
+# end
+# end
+defappend_only_set(field_name,from:)
+ fields<<DerivedFields::AppendOnlySet.new(field_name,from)
+ end
+
+ # Configures `field_name` (on the derived indexing type) to contain a single immutable value from the
+# `from` field on the source type. Immutability is enforced by triggering an indexing failure with a
+# clear error if any event's source value is different from the value already indexed on this field.
+#
+# @param field_name [String] name of field on the derived indexing type to store the derived value
+# @param from [String] path to field on the source type to source values from
+# @param nullable [Boolean] whether the field is allowed to be set to `null`. When set to false, events
+# that contain a `null` value in the `from` field will be rejected instead of setting the field’s value
+# to `null`.
+# @param can_change_from_null [Boolean] whether a one-time mutation of the field value is allowed from
+# `null` to a non-`null` value. This can be useful when dealing with a field that may not have a value
+# on all source events. For example, if the source field was not initially part of the schema of your
+# source dataset, you may have old records that lack a value for this field. When set, this option
+# allows a one-time mutation of the field value from `null` to a non-`null` value. Once set to a
+# non-`null` value, any additional `null` values that are encountered will be ignored (ensuring that
+# the indexed data converges on the same state regardless of the order the events are ingested in).
+# Note: this option cannot be enabled when `nullable: false` has been set.
+# @return [DerivedFields::ImmutableValue]
+#
+# @example
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "StudentCourseEnrollment" do |t|
+# t.field "id", "ID"
+# t.field "courseId", "ID"
+# t.field "courseName", "String"
+#
+# t.index "student_course_enrollments"
+#
+# t.derive_indexed_type_fields "Course", from_id: "courseId" do |derive|
+# derive.immutable_value "name", from: "courseName"
+# end
+# end
+#
+# schema.object_type "Course" do |t|
+# t.field "id", "ID"
+# t.field "name", "String"
+#
+# t.index "courses"
+# end
+# end
+defimmutable_value(field_name,from:,nullable:true,can_change_from_null:false)
+ if!nullable&&can_change_from_null
+ raiseErrors::SchemaError,"`can_change_from_null: true` is not allowed with `nullable: false` (as there would be no `null` values to change from)."
+ end
+
+ fields<<DerivedFields::ImmutableValue.new(
+ destination_field:field_name,
+ source_field:from,
+ nullable:nullable,
+ can_change_from_null:can_change_from_null
+ )
+ end
+
+ # Configures `field_name` (on the derived indexing type) to contain the minimum of all values from the `from`
+# field on the source type.
+#
+# @param field_name [String] name of field on the derived indexing type to store the derived value
+# @param from [String] path to field on the source type to source values from
+# @return [DerivedIndexedType::MinOrMaxValue]
+#
+# @example
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "StudentCourseEnrollment" do |t|
+# t.field "id", "ID"
+# t.field "courseId", "ID"
+# t.field "courseStartDate", "Date"
+#
+# t.index "student_course_enrollments"
+#
+# t.derive_indexed_type_fields "Course", from_id: "courseId" do |derive|
+# derive.min_value "firstOfferedDate", from: "courseStartDate"
+# end
+# end
+#
+# schema.object_type "Course" do |t|
+# t.field "id", "ID"
+# t.field "firstOfferedDate", "Date"
+#
+# t.index "courses"
+# end
+# end
+defmin_value(field_name,from:)
+ fields<<DerivedFields::MinOrMaxValue.new(field_name,from,:min)
+ end
+
+ # Configures `field_name` (on the derived indexing type) to contain the maximum of all values from the `from`
+# field on the source type.
+#
+# @param field_name [String] name of field on the derived indexing type to store the derived value
+# @param from [String] path to field on the source type to source values from
+# @return [DerivedIndexedType::MinOrMaxValue]
+#
+# @example
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "StudentCourseEnrollment" do |t|
+# t.field "id", "ID"
+# t.field "courseId", "ID"
+# t.field "courseStartDate", "Date"
+#
+# t.index "student_course_enrollments"
+#
+# t.derive_indexed_type_fields "Course", from_id: "courseId" do |derive|
+# derive.max_value "mostRecentlyOfferedDate", from: "courseStartDate"
+# end
+# end
+#
+# schema.object_type "Course" do |t|
+# t.field "id", "ID"
+# t.field "mostRecentlyOfferedDate", "Date"
+#
+# t.index "courses"
+# end
+# end
+defmax_value(field_name,from:)
+ fields<<DerivedFields::MinOrMaxValue.new(field_name,from,:max)
+ end
+
+ # @return [Scripting::Script] Painless script that will maintain the derived fields
+# @api private
+defpainless_script
+ Scripting::Script.new(
+ source:generate_script.strip,
+ name:"#{destination_type_ref}_from_#{source_type.name}",
+ language:"painless",
+ context:"update"
+ )
+ end
+
+ # @return [SchemaArtifacts::RuntimeMetadata::UpdateTarget] runtime metadata for the source type
+# @api private
+defruntime_metadata_for_source_type
+ SchemaArtifacts::RuntimeMetadata::UpdateTarget.new(
+ type:destination_type_ref.name,
+ relationship:nil,
+ script_id:painless_script.id,
+ id_source:id_source,
+ routing_value_source:routing_value_source,
+ rollover_timestamp_value_source:rollover_timestamp_value_source,
+ metadata_params:{},
+ data_params:fields.map(&:source_field).to_hdo|f|
+ [f,SchemaArtifacts::RuntimeMetadata::DynamicParam.new(source_path:f,cardinality::many)]
+ end
+ )
+ end
+
+ private
+
+ defgenerate_script
+ iffields.empty?
+ raiseErrors::SchemaError,"`derive_indexed_type_fields` definition for #{destination_type_ref} (from #{source_type.name}) " \
+ "has no derived field definitions."
+ end
+
+ sorted_fields=fields.sort_by(&:destination_field)
+
+ # We use `uniq` here to avoid re-doing the same setup multiple times, since multiple fields can sometimes
+# need the same setup (such as initializing a common parent field to an empty map).
+function_defs=sorted_fields.flat_map(&:function_definitions).uniq.map(&:strip).sort
+
+ setup_statements=[STATIC_SETUP_STATEMENTS]+sorted_fields.flat_map(&:setup_statements).uniq.map(&:strip)
+
+ apply_update_statements=sorted_fields.map{|f|apply_update_statement(f).strip}
+
+ # Note: comments in the script are effectively "free" since:
+#
+# - The compiler will strip them out.
+# - We only send the script to the datastore once (when configuring the cluster), and later
+# reference it only by id--so we don't pay for the larger payload on each indexing request.
+<<~EOS
+#{function_defs.join("\n\n")}
+
+#{setup_statements.join("\n")}
+
+#{apply_update_statements.join("\n")}
+
+ if (!#{SCRIPT_ERRORS_VAR}.isEmpty()) {
+ throw new IllegalArgumentException("#{DERIVED_INDEX_FAILURE_MESSAGE_PREAMBLE}: " + #{SCRIPT_ERRORS_VAR}.join(" "));
+ }
+
+ // For records with no new values to index, only skip the update if the document itself doesn't already exist.
+ // Otherwise create an (empty) document to reflect the fact that the id has been seen.
+ if (ctx._source.id != null && #{sorted_fields.map{|f|was_noop_variable(f)}.join(" && ")}) {
+ ctx.op = 'none';
+ } else {
+ // Here we set `_source.id` because if we don't, it'll never be set, making these docs subtly
+ // different from docs indexed the normal way.
+ //
+ // Note also that we MUST use `params.id` instead of `ctx._id`. The latter works on an update
+ // of an existing document, but is unavailable when we are inserting the document for the first time.
+ ctx._source.id = params.id;
+ }
+ EOS
+end
+
+ defapply_update_statement(field)
+ "boolean #{was_noop_variable(field)} = !#{field.apply_operation_returning_update_status};"
+ end
+
+ defwas_noop_variable(field)
+ "#{field.destination_field.gsub(".","__")}_was_noop"
+ end
+
+ SCRIPT_ERRORS_VAR="scriptErrors"
+
+ STATIC_SETUP_STATEMENTS=<<~EOS.strip
+ Map data = params.data;
+ // A variable to accumulate script errors so that we can surface _all_ issues and not just the first.
+ List #{SCRIPT_ERRORS_VAR} = new ArrayList();
+ EOS
+end
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/indexing/derived_indexed_type.rb', line 67
+
+classDerivedIndexedType<::Struct.new(
+ :source_type,
+ :destination_type_ref,
+ :id_source,
+ :routing_value_source,
+ :rollover_timestamp_value_source,
+ :fields
+)
+ # @param source_type [SchemaElements::ObjectType] the type used as a source for this derive type
+# @param destination_type_ref [SchemaElements::TypeReference] the derived type
+# @param id_source [String] path to field on the source type used as `id` on the derived type
+# @param routing_value_source [String, nil] path to field on the source type used for shard routing
+# @param rollover_timestamp_value_source [String, nil] path to field on the source type used as the timestamp field for rollover
+# @yield [DerivedIndexedType] the `DerivedIndexedType` instance
+# @api private
+definitialize(
+ source_type:,
+ destination_type_ref:,
+ id_source:,
+ routing_value_source:,
+ rollover_timestamp_value_source:
+ )
+ fields=[]# : ::Array[_DerivedField]
+super(
+ source_type:source_type,
+ destination_type_ref:destination_type_ref,
+ id_source:id_source,
+ routing_value_source:routing_value_source,
+ rollover_timestamp_value_source:rollover_timestamp_value_source,
+ fields:fields
+ )
+ yieldself
+ end
+
+ # Configures `field_name` (on the derived indexing type) to contain the set union of all values from
+# the `from` field on the source type. Values are only ever appended to the set, so the field will
+# act as an append-only set.
+#
+# @param field_name [String] name of field on the derived indexing type to store the derived set
+# @param from [String] path to field on the source type to source values from
+# @return [DerivedIndexedType::AppendOnlySet]
+#
+# @example
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "StudentCourseEnrollment" do |t|
+# t.field "id", "ID"
+# t.field "courseId", "ID"
+# t.field "studentName", "String"
+#
+# t.index "student_course_enrollments"
+#
+# t.derive_indexed_type_fields "Course", from_id: "courseId" do |derive|
+# derive.append_only_set "students", from: "studentName"
+# end
+# end
+#
+# schema.object_type "Course" do |t|
+# t.field "id", "ID"
+# t.field "students", "[String!]!"
+#
+# t.index "courses"
+# end
+# end
+defappend_only_set(field_name,from:)
+ fields<<DerivedFields::AppendOnlySet.new(field_name,from)
+ end
+
+ # Configures `field_name` (on the derived indexing type) to contain a single immutable value from the
+# `from` field on the source type. Immutability is enforced by triggering an indexing failure with a
+# clear error if any event's source value is different from the value already indexed on this field.
+#
+# @param field_name [String] name of field on the derived indexing type to store the derived value
+# @param from [String] path to field on the source type to source values from
+# @param nullable [Boolean] whether the field is allowed to be set to `null`. When set to false, events
+# that contain a `null` value in the `from` field will be rejected instead of setting the field’s value
+# to `null`.
+# @param can_change_from_null [Boolean] whether a one-time mutation of the field value is allowed from
+# `null` to a non-`null` value. This can be useful when dealing with a field that may not have a value
+# on all source events. For example, if the source field was not initially part of the schema of your
+# source dataset, you may have old records that lack a value for this field. When set, this option
+# allows a one-time mutation of the field value from `null` to a non-`null` value. Once set to a
+# non-`null` value, any additional `null` values that are encountered will be ignored (ensuring that
+# the indexed data converges on the same state regardless of the order the events are ingested in).
+# Note: this option cannot be enabled when `nullable: false` has been set.
+# @return [DerivedFields::ImmutableValue]
+#
+# @example
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "StudentCourseEnrollment" do |t|
+# t.field "id", "ID"
+# t.field "courseId", "ID"
+# t.field "courseName", "String"
+#
+# t.index "student_course_enrollments"
+#
+# t.derive_indexed_type_fields "Course", from_id: "courseId" do |derive|
+# derive.immutable_value "name", from: "courseName"
+# end
+# end
+#
+# schema.object_type "Course" do |t|
+# t.field "id", "ID"
+# t.field "name", "String"
+#
+# t.index "courses"
+# end
+# end
+defimmutable_value(field_name,from:,nullable:true,can_change_from_null:false)
+ if!nullable&&can_change_from_null
+ raiseErrors::SchemaError,"`can_change_from_null: true` is not allowed with `nullable: false` (as there would be no `null` values to change from)."
+ end
+
+ fields<<DerivedFields::ImmutableValue.new(
+ destination_field:field_name,
+ source_field:from,
+ nullable:nullable,
+ can_change_from_null:can_change_from_null
+ )
+ end
+
+ # Configures `field_name` (on the derived indexing type) to contain the minimum of all values from the `from`
+# field on the source type.
+#
+# @param field_name [String] name of field on the derived indexing type to store the derived value
+# @param from [String] path to field on the source type to source values from
+# @return [DerivedIndexedType::MinOrMaxValue]
+#
+# @example
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "StudentCourseEnrollment" do |t|
+# t.field "id", "ID"
+# t.field "courseId", "ID"
+# t.field "courseStartDate", "Date"
+#
+# t.index "student_course_enrollments"
+#
+# t.derive_indexed_type_fields "Course", from_id: "courseId" do |derive|
+# derive.min_value "firstOfferedDate", from: "courseStartDate"
+# end
+# end
+#
+# schema.object_type "Course" do |t|
+# t.field "id", "ID"
+# t.field "firstOfferedDate", "Date"
+#
+# t.index "courses"
+# end
+# end
+defmin_value(field_name,from:)
+ fields<<DerivedFields::MinOrMaxValue.new(field_name,from,:min)
+ end
+
+ # Configures `field_name` (on the derived indexing type) to contain the maximum of all values from the `from`
+# field on the source type.
+#
+# @param field_name [String] name of field on the derived indexing type to store the derived value
+# @param from [String] path to field on the source type to source values from
+# @return [DerivedIndexedType::MinOrMaxValue]
+#
+# @example
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "StudentCourseEnrollment" do |t|
+# t.field "id", "ID"
+# t.field "courseId", "ID"
+# t.field "courseStartDate", "Date"
+#
+# t.index "student_course_enrollments"
+#
+# t.derive_indexed_type_fields "Course", from_id: "courseId" do |derive|
+# derive.max_value "mostRecentlyOfferedDate", from: "courseStartDate"
+# end
+# end
+#
+# schema.object_type "Course" do |t|
+# t.field "id", "ID"
+# t.field "mostRecentlyOfferedDate", "Date"
+#
+# t.index "courses"
+# end
+# end
+defmax_value(field_name,from:)
+ fields<<DerivedFields::MinOrMaxValue.new(field_name,from,:max)
+ end
+
+ # @return [Scripting::Script] Painless script that will maintain the derived fields
+# @api private
+defpainless_script
+ Scripting::Script.new(
+ source:generate_script.strip,
+ name:"#{destination_type_ref}_from_#{source_type.name}",
+ language:"painless",
+ context:"update"
+ )
+ end
+
+ # @return [SchemaArtifacts::RuntimeMetadata::UpdateTarget] runtime metadata for the source type
+# @api private
+defruntime_metadata_for_source_type
+ SchemaArtifacts::RuntimeMetadata::UpdateTarget.new(
+ type:destination_type_ref.name,
+ relationship:nil,
+ script_id:painless_script.id,
+ id_source:id_source,
+ routing_value_source:routing_value_source,
+ rollover_timestamp_value_source:rollover_timestamp_value_source,
+ metadata_params:{},
+ data_params:fields.map(&:source_field).to_hdo|f|
+ [f,SchemaArtifacts::RuntimeMetadata::DynamicParam.new(source_path:f,cardinality::many)]
+ end
+ )
+ end
+
+ private
+
+ defgenerate_script
+ iffields.empty?
+ raiseErrors::SchemaError,"`derive_indexed_type_fields` definition for #{destination_type_ref} (from #{source_type.name}) " \
+ "has no derived field definitions."
+ end
+
+ sorted_fields=fields.sort_by(&:destination_field)
+
+ # We use `uniq` here to avoid re-doing the same setup multiple times, since multiple fields can sometimes
+# need the same setup (such as initializing a common parent field to an empty map).
+function_defs=sorted_fields.flat_map(&:function_definitions).uniq.map(&:strip).sort
+
+ setup_statements=[STATIC_SETUP_STATEMENTS]+sorted_fields.flat_map(&:setup_statements).uniq.map(&:strip)
+
+ apply_update_statements=sorted_fields.map{|f|apply_update_statement(f).strip}
+
+ # Note: comments in the script are effectively "free" since:
+#
+# - The compiler will strip them out.
+# - We only send the script to the datastore once (when configuring the cluster), and later
+# reference it only by id--so we don't pay for the larger payload on each indexing request.
+<<~EOS
+#{function_defs.join("\n\n")}
+
+#{setup_statements.join("\n")}
+
+#{apply_update_statements.join("\n")}
+
+ if (!#{SCRIPT_ERRORS_VAR}.isEmpty()) {
+ throw new IllegalArgumentException("#{DERIVED_INDEX_FAILURE_MESSAGE_PREAMBLE}: " + #{SCRIPT_ERRORS_VAR}.join(" "));
+ }
+
+ // For records with no new values to index, only skip the update if the document itself doesn't already exist.
+ // Otherwise create an (empty) document to reflect the fact that the id has been seen.
+ if (ctx._source.id != null && #{sorted_fields.map{|f|was_noop_variable(f)}.join(" && ")}) {
+ ctx.op = 'none';
+ } else {
+ // Here we set `_source.id` because if we don't, it'll never be set, making these docs subtly
+ // different from docs indexed the normal way.
+ //
+ // Note also that we MUST use `params.id` instead of `ctx._id`. The latter works on an update
+ // of an existing document, but is unavailable when we are inserting the document for the first time.
+ ctx._source.id = params.id;
+ }
+ EOS
+end
+
+ defapply_update_statement(field)
+ "boolean #{was_noop_variable(field)} = !#{field.apply_operation_returning_update_status};"
+ end
+
+ defwas_noop_variable(field)
+ "#{field.destination_field.gsub(".","__")}_was_noop"
+ end
+
+ SCRIPT_ERRORS_VAR="scriptErrors"
+
+ STATIC_SETUP_STATEMENTS=<<~EOS.strip
+ Map data = params.data;
+ // A variable to accumulate script errors so that we can surface _all_ issues and not just the first.
+ List #{SCRIPT_ERRORS_VAR} = new ArrayList();
+ EOS
+end
+
+
+
+
+
+
+
+
+
+
+ #routing_value_source ⇒ String?
+
+
+
+
+
+
+
+
Returns path to field on the source type used for shard routing.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String, nil)
+
+
+
+ —
+
path to field on the source type used for shard routing
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/indexing/derived_indexed_type.rb', line 67
+
+classDerivedIndexedType<::Struct.new(
+ :source_type,
+ :destination_type_ref,
+ :id_source,
+ :routing_value_source,
+ :rollover_timestamp_value_source,
+ :fields
+)
+ # @param source_type [SchemaElements::ObjectType] the type used as a source for this derive type
+# @param destination_type_ref [SchemaElements::TypeReference] the derived type
+# @param id_source [String] path to field on the source type used as `id` on the derived type
+# @param routing_value_source [String, nil] path to field on the source type used for shard routing
+# @param rollover_timestamp_value_source [String, nil] path to field on the source type used as the timestamp field for rollover
+# @yield [DerivedIndexedType] the `DerivedIndexedType` instance
+# @api private
+definitialize(
+ source_type:,
+ destination_type_ref:,
+ id_source:,
+ routing_value_source:,
+ rollover_timestamp_value_source:
+ )
+ fields=[]# : ::Array[_DerivedField]
+super(
+ source_type:source_type,
+ destination_type_ref:destination_type_ref,
+ id_source:id_source,
+ routing_value_source:routing_value_source,
+ rollover_timestamp_value_source:rollover_timestamp_value_source,
+ fields:fields
+ )
+ yieldself
+ end
+
+ # Configures `field_name` (on the derived indexing type) to contain the set union of all values from
+# the `from` field on the source type. Values are only ever appended to the set, so the field will
+# act as an append-only set.
+#
+# @param field_name [String] name of field on the derived indexing type to store the derived set
+# @param from [String] path to field on the source type to source values from
+# @return [DerivedIndexedType::AppendOnlySet]
+#
+# @example
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "StudentCourseEnrollment" do |t|
+# t.field "id", "ID"
+# t.field "courseId", "ID"
+# t.field "studentName", "String"
+#
+# t.index "student_course_enrollments"
+#
+# t.derive_indexed_type_fields "Course", from_id: "courseId" do |derive|
+# derive.append_only_set "students", from: "studentName"
+# end
+# end
+#
+# schema.object_type "Course" do |t|
+# t.field "id", "ID"
+# t.field "students", "[String!]!"
+#
+# t.index "courses"
+# end
+# end
+defappend_only_set(field_name,from:)
+ fields<<DerivedFields::AppendOnlySet.new(field_name,from)
+ end
+
+ # Configures `field_name` (on the derived indexing type) to contain a single immutable value from the
+# `from` field on the source type. Immutability is enforced by triggering an indexing failure with a
+# clear error if any event's source value is different from the value already indexed on this field.
+#
+# @param field_name [String] name of field on the derived indexing type to store the derived value
+# @param from [String] path to field on the source type to source values from
+# @param nullable [Boolean] whether the field is allowed to be set to `null`. When set to false, events
+# that contain a `null` value in the `from` field will be rejected instead of setting the field’s value
+# to `null`.
+# @param can_change_from_null [Boolean] whether a one-time mutation of the field value is allowed from
+# `null` to a non-`null` value. This can be useful when dealing with a field that may not have a value
+# on all source events. For example, if the source field was not initially part of the schema of your
+# source dataset, you may have old records that lack a value for this field. When set, this option
+# allows a one-time mutation of the field value from `null` to a non-`null` value. Once set to a
+# non-`null` value, any additional `null` values that are encountered will be ignored (ensuring that
+# the indexed data converges on the same state regardless of the order the events are ingested in).
+# Note: this option cannot be enabled when `nullable: false` has been set.
+# @return [DerivedFields::ImmutableValue]
+#
+# @example
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "StudentCourseEnrollment" do |t|
+# t.field "id", "ID"
+# t.field "courseId", "ID"
+# t.field "courseName", "String"
+#
+# t.index "student_course_enrollments"
+#
+# t.derive_indexed_type_fields "Course", from_id: "courseId" do |derive|
+# derive.immutable_value "name", from: "courseName"
+# end
+# end
+#
+# schema.object_type "Course" do |t|
+# t.field "id", "ID"
+# t.field "name", "String"
+#
+# t.index "courses"
+# end
+# end
+defimmutable_value(field_name,from:,nullable:true,can_change_from_null:false)
+ if!nullable&&can_change_from_null
+ raiseErrors::SchemaError,"`can_change_from_null: true` is not allowed with `nullable: false` (as there would be no `null` values to change from)."
+ end
+
+ fields<<DerivedFields::ImmutableValue.new(
+ destination_field:field_name,
+ source_field:from,
+ nullable:nullable,
+ can_change_from_null:can_change_from_null
+ )
+ end
+
+ # Configures `field_name` (on the derived indexing type) to contain the minimum of all values from the `from`
+# field on the source type.
+#
+# @param field_name [String] name of field on the derived indexing type to store the derived value
+# @param from [String] path to field on the source type to source values from
+# @return [DerivedIndexedType::MinOrMaxValue]
+#
+# @example
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "StudentCourseEnrollment" do |t|
+# t.field "id", "ID"
+# t.field "courseId", "ID"
+# t.field "courseStartDate", "Date"
+#
+# t.index "student_course_enrollments"
+#
+# t.derive_indexed_type_fields "Course", from_id: "courseId" do |derive|
+# derive.min_value "firstOfferedDate", from: "courseStartDate"
+# end
+# end
+#
+# schema.object_type "Course" do |t|
+# t.field "id", "ID"
+# t.field "firstOfferedDate", "Date"
+#
+# t.index "courses"
+# end
+# end
+defmin_value(field_name,from:)
+ fields<<DerivedFields::MinOrMaxValue.new(field_name,from,:min)
+ end
+
+ # Configures `field_name` (on the derived indexing type) to contain the maximum of all values from the `from`
+# field on the source type.
+#
+# @param field_name [String] name of field on the derived indexing type to store the derived value
+# @param from [String] path to field on the source type to source values from
+# @return [DerivedIndexedType::MinOrMaxValue]
+#
+# @example
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "StudentCourseEnrollment" do |t|
+# t.field "id", "ID"
+# t.field "courseId", "ID"
+# t.field "courseStartDate", "Date"
+#
+# t.index "student_course_enrollments"
+#
+# t.derive_indexed_type_fields "Course", from_id: "courseId" do |derive|
+# derive.max_value "mostRecentlyOfferedDate", from: "courseStartDate"
+# end
+# end
+#
+# schema.object_type "Course" do |t|
+# t.field "id", "ID"
+# t.field "mostRecentlyOfferedDate", "Date"
+#
+# t.index "courses"
+# end
+# end
+defmax_value(field_name,from:)
+ fields<<DerivedFields::MinOrMaxValue.new(field_name,from,:max)
+ end
+
+ # @return [Scripting::Script] Painless script that will maintain the derived fields
+# @api private
+defpainless_script
+ Scripting::Script.new(
+ source:generate_script.strip,
+ name:"#{destination_type_ref}_from_#{source_type.name}",
+ language:"painless",
+ context:"update"
+ )
+ end
+
+ # @return [SchemaArtifacts::RuntimeMetadata::UpdateTarget] runtime metadata for the source type
+# @api private
+defruntime_metadata_for_source_type
+ SchemaArtifacts::RuntimeMetadata::UpdateTarget.new(
+ type:destination_type_ref.name,
+ relationship:nil,
+ script_id:painless_script.id,
+ id_source:id_source,
+ routing_value_source:routing_value_source,
+ rollover_timestamp_value_source:rollover_timestamp_value_source,
+ metadata_params:{},
+ data_params:fields.map(&:source_field).to_hdo|f|
+ [f,SchemaArtifacts::RuntimeMetadata::DynamicParam.new(source_path:f,cardinality::many)]
+ end
+ )
+ end
+
+ private
+
+ defgenerate_script
+ iffields.empty?
+ raiseErrors::SchemaError,"`derive_indexed_type_fields` definition for #{destination_type_ref} (from #{source_type.name}) " \
+ "has no derived field definitions."
+ end
+
+ sorted_fields=fields.sort_by(&:destination_field)
+
+ # We use `uniq` here to avoid re-doing the same setup multiple times, since multiple fields can sometimes
+# need the same setup (such as initializing a common parent field to an empty map).
+function_defs=sorted_fields.flat_map(&:function_definitions).uniq.map(&:strip).sort
+
+ setup_statements=[STATIC_SETUP_STATEMENTS]+sorted_fields.flat_map(&:setup_statements).uniq.map(&:strip)
+
+ apply_update_statements=sorted_fields.map{|f|apply_update_statement(f).strip}
+
+ # Note: comments in the script are effectively "free" since:
+#
+# - The compiler will strip them out.
+# - We only send the script to the datastore once (when configuring the cluster), and later
+# reference it only by id--so we don't pay for the larger payload on each indexing request.
+<<~EOS
+#{function_defs.join("\n\n")}
+
+#{setup_statements.join("\n")}
+
+#{apply_update_statements.join("\n")}
+
+ if (!#{SCRIPT_ERRORS_VAR}.isEmpty()) {
+ throw new IllegalArgumentException("#{DERIVED_INDEX_FAILURE_MESSAGE_PREAMBLE}: " + #{SCRIPT_ERRORS_VAR}.join(" "));
+ }
+
+ // For records with no new values to index, only skip the update if the document itself doesn't already exist.
+ // Otherwise create an (empty) document to reflect the fact that the id has been seen.
+ if (ctx._source.id != null && #{sorted_fields.map{|f|was_noop_variable(f)}.join(" && ")}) {
+ ctx.op = 'none';
+ } else {
+ // Here we set `_source.id` because if we don't, it'll never be set, making these docs subtly
+ // different from docs indexed the normal way.
+ //
+ // Note also that we MUST use `params.id` instead of `ctx._id`. The latter works on an update
+ // of an existing document, but is unavailable when we are inserting the document for the first time.
+ ctx._source.id = params.id;
+ }
+ EOS
+end
+
+ defapply_update_statement(field)
+ "boolean #{was_noop_variable(field)} = !#{field.apply_operation_returning_update_status};"
+ end
+
+ defwas_noop_variable(field)
+ "#{field.destination_field.gsub(".","__")}_was_noop"
+ end
+
+ SCRIPT_ERRORS_VAR="scriptErrors"
+
+ STATIC_SETUP_STATEMENTS=<<~EOS.strip
+ Map data = params.data;
+ // A variable to accumulate script errors so that we can surface _all_ issues and not just the first.
+ List #{SCRIPT_ERRORS_VAR} = new ArrayList();
+ EOS
+end
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/indexing/derived_indexed_type.rb', line 67
+
+classDerivedIndexedType<::Struct.new(
+ :source_type,
+ :destination_type_ref,
+ :id_source,
+ :routing_value_source,
+ :rollover_timestamp_value_source,
+ :fields
+)
+ # @param source_type [SchemaElements::ObjectType] the type used as a source for this derive type
+# @param destination_type_ref [SchemaElements::TypeReference] the derived type
+# @param id_source [String] path to field on the source type used as `id` on the derived type
+# @param routing_value_source [String, nil] path to field on the source type used for shard routing
+# @param rollover_timestamp_value_source [String, nil] path to field on the source type used as the timestamp field for rollover
+# @yield [DerivedIndexedType] the `DerivedIndexedType` instance
+# @api private
+definitialize(
+ source_type:,
+ destination_type_ref:,
+ id_source:,
+ routing_value_source:,
+ rollover_timestamp_value_source:
+ )
+ fields=[]# : ::Array[_DerivedField]
+super(
+ source_type:source_type,
+ destination_type_ref:destination_type_ref,
+ id_source:id_source,
+ routing_value_source:routing_value_source,
+ rollover_timestamp_value_source:rollover_timestamp_value_source,
+ fields:fields
+ )
+ yieldself
+ end
+
+ # Configures `field_name` (on the derived indexing type) to contain the set union of all values from
+# the `from` field on the source type. Values are only ever appended to the set, so the field will
+# act as an append-only set.
+#
+# @param field_name [String] name of field on the derived indexing type to store the derived set
+# @param from [String] path to field on the source type to source values from
+# @return [DerivedIndexedType::AppendOnlySet]
+#
+# @example
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "StudentCourseEnrollment" do |t|
+# t.field "id", "ID"
+# t.field "courseId", "ID"
+# t.field "studentName", "String"
+#
+# t.index "student_course_enrollments"
+#
+# t.derive_indexed_type_fields "Course", from_id: "courseId" do |derive|
+# derive.append_only_set "students", from: "studentName"
+# end
+# end
+#
+# schema.object_type "Course" do |t|
+# t.field "id", "ID"
+# t.field "students", "[String!]!"
+#
+# t.index "courses"
+# end
+# end
+defappend_only_set(field_name,from:)
+ fields<<DerivedFields::AppendOnlySet.new(field_name,from)
+ end
+
+ # Configures `field_name` (on the derived indexing type) to contain a single immutable value from the
+# `from` field on the source type. Immutability is enforced by triggering an indexing failure with a
+# clear error if any event's source value is different from the value already indexed on this field.
+#
+# @param field_name [String] name of field on the derived indexing type to store the derived value
+# @param from [String] path to field on the source type to source values from
+# @param nullable [Boolean] whether the field is allowed to be set to `null`. When set to false, events
+# that contain a `null` value in the `from` field will be rejected instead of setting the field’s value
+# to `null`.
+# @param can_change_from_null [Boolean] whether a one-time mutation of the field value is allowed from
+# `null` to a non-`null` value. This can be useful when dealing with a field that may not have a value
+# on all source events. For example, if the source field was not initially part of the schema of your
+# source dataset, you may have old records that lack a value for this field. When set, this option
+# allows a one-time mutation of the field value from `null` to a non-`null` value. Once set to a
+# non-`null` value, any additional `null` values that are encountered will be ignored (ensuring that
+# the indexed data converges on the same state regardless of the order the events are ingested in).
+# Note: this option cannot be enabled when `nullable: false` has been set.
+# @return [DerivedFields::ImmutableValue]
+#
+# @example
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "StudentCourseEnrollment" do |t|
+# t.field "id", "ID"
+# t.field "courseId", "ID"
+# t.field "courseName", "String"
+#
+# t.index "student_course_enrollments"
+#
+# t.derive_indexed_type_fields "Course", from_id: "courseId" do |derive|
+# derive.immutable_value "name", from: "courseName"
+# end
+# end
+#
+# schema.object_type "Course" do |t|
+# t.field "id", "ID"
+# t.field "name", "String"
+#
+# t.index "courses"
+# end
+# end
+defimmutable_value(field_name,from:,nullable:true,can_change_from_null:false)
+ if!nullable&&can_change_from_null
+ raiseErrors::SchemaError,"`can_change_from_null: true` is not allowed with `nullable: false` (as there would be no `null` values to change from)."
+ end
+
+ fields<<DerivedFields::ImmutableValue.new(
+ destination_field:field_name,
+ source_field:from,
+ nullable:nullable,
+ can_change_from_null:can_change_from_null
+ )
+ end
+
+ # Configures `field_name` (on the derived indexing type) to contain the minimum of all values from the `from`
+# field on the source type.
+#
+# @param field_name [String] name of field on the derived indexing type to store the derived value
+# @param from [String] path to field on the source type to source values from
+# @return [DerivedIndexedType::MinOrMaxValue]
+#
+# @example
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "StudentCourseEnrollment" do |t|
+# t.field "id", "ID"
+# t.field "courseId", "ID"
+# t.field "courseStartDate", "Date"
+#
+# t.index "student_course_enrollments"
+#
+# t.derive_indexed_type_fields "Course", from_id: "courseId" do |derive|
+# derive.min_value "firstOfferedDate", from: "courseStartDate"
+# end
+# end
+#
+# schema.object_type "Course" do |t|
+# t.field "id", "ID"
+# t.field "firstOfferedDate", "Date"
+#
+# t.index "courses"
+# end
+# end
+defmin_value(field_name,from:)
+ fields<<DerivedFields::MinOrMaxValue.new(field_name,from,:min)
+ end
+
+ # Configures `field_name` (on the derived indexing type) to contain the maximum of all values from the `from`
+# field on the source type.
+#
+# @param field_name [String] name of field on the derived indexing type to store the derived value
+# @param from [String] path to field on the source type to source values from
+# @return [DerivedIndexedType::MinOrMaxValue]
+#
+# @example
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "StudentCourseEnrollment" do |t|
+# t.field "id", "ID"
+# t.field "courseId", "ID"
+# t.field "courseStartDate", "Date"
+#
+# t.index "student_course_enrollments"
+#
+# t.derive_indexed_type_fields "Course", from_id: "courseId" do |derive|
+# derive.max_value "mostRecentlyOfferedDate", from: "courseStartDate"
+# end
+# end
+#
+# schema.object_type "Course" do |t|
+# t.field "id", "ID"
+# t.field "mostRecentlyOfferedDate", "Date"
+#
+# t.index "courses"
+# end
+# end
+defmax_value(field_name,from:)
+ fields<<DerivedFields::MinOrMaxValue.new(field_name,from,:max)
+ end
+
+ # @return [Scripting::Script] Painless script that will maintain the derived fields
+# @api private
+defpainless_script
+ Scripting::Script.new(
+ source:generate_script.strip,
+ name:"#{destination_type_ref}_from_#{source_type.name}",
+ language:"painless",
+ context:"update"
+ )
+ end
+
+ # @return [SchemaArtifacts::RuntimeMetadata::UpdateTarget] runtime metadata for the source type
+# @api private
+defruntime_metadata_for_source_type
+ SchemaArtifacts::RuntimeMetadata::UpdateTarget.new(
+ type:destination_type_ref.name,
+ relationship:nil,
+ script_id:painless_script.id,
+ id_source:id_source,
+ routing_value_source:routing_value_source,
+ rollover_timestamp_value_source:rollover_timestamp_value_source,
+ metadata_params:{},
+ data_params:fields.map(&:source_field).to_hdo|f|
+ [f,SchemaArtifacts::RuntimeMetadata::DynamicParam.new(source_path:f,cardinality::many)]
+ end
+ )
+ end
+
+ private
+
+ defgenerate_script
+ iffields.empty?
+ raiseErrors::SchemaError,"`derive_indexed_type_fields` definition for #{destination_type_ref} (from #{source_type.name}) " \
+ "has no derived field definitions."
+ end
+
+ sorted_fields=fields.sort_by(&:destination_field)
+
+ # We use `uniq` here to avoid re-doing the same setup multiple times, since multiple fields can sometimes
+# need the same setup (such as initializing a common parent field to an empty map).
+function_defs=sorted_fields.flat_map(&:function_definitions).uniq.map(&:strip).sort
+
+ setup_statements=[STATIC_SETUP_STATEMENTS]+sorted_fields.flat_map(&:setup_statements).uniq.map(&:strip)
+
+ apply_update_statements=sorted_fields.map{|f|apply_update_statement(f).strip}
+
+ # Note: comments in the script are effectively "free" since:
+#
+# - The compiler will strip them out.
+# - We only send the script to the datastore once (when configuring the cluster), and later
+# reference it only by id--so we don't pay for the larger payload on each indexing request.
+<<~EOS
+#{function_defs.join("\n\n")}
+
+#{setup_statements.join("\n")}
+
+#{apply_update_statements.join("\n")}
+
+ if (!#{SCRIPT_ERRORS_VAR}.isEmpty()) {
+ throw new IllegalArgumentException("#{DERIVED_INDEX_FAILURE_MESSAGE_PREAMBLE}: " + #{SCRIPT_ERRORS_VAR}.join(" "));
+ }
+
+ // For records with no new values to index, only skip the update if the document itself doesn't already exist.
+ // Otherwise create an (empty) document to reflect the fact that the id has been seen.
+ if (ctx._source.id != null && #{sorted_fields.map{|f|was_noop_variable(f)}.join(" && ")}) {
+ ctx.op = 'none';
+ } else {
+ // Here we set `_source.id` because if we don't, it'll never be set, making these docs subtly
+ // different from docs indexed the normal way.
+ //
+ // Note also that we MUST use `params.id` instead of `ctx._id`. The latter works on an update
+ // of an existing document, but is unavailable when we are inserting the document for the first time.
+ ctx._source.id = params.id;
+ }
+ EOS
+end
+
+ defapply_update_statement(field)
+ "boolean #{was_noop_variable(field)} = !#{field.apply_operation_returning_update_status};"
+ end
+
+ defwas_noop_variable(field)
+ "#{field.destination_field.gsub(".","__")}_was_noop"
+ end
+
+ SCRIPT_ERRORS_VAR="scriptErrors"
+
+ STATIC_SETUP_STATEMENTS=<<~EOS.strip
+ Map data = params.data;
+ // A variable to accumulate script errors so that we can surface _all_ issues and not just the first.
+ List #{SCRIPT_ERRORS_VAR} = new ArrayList();
+ EOS
+end
Configures field_name (on the derived indexing type) to contain the set union of all values from
+the from field on the source type. Values are only ever appended to the set, so the field will
+act as an append-only set.
Configures field_name (on the derived indexing type) to contain a single immutable value from the
+from field on the source type. Immutability is enforced by triggering an indexing failure with a
+clear error if any event’s source value is different from the value already indexed on this field.
whether the field is allowed to be set to null. When set to false, events
+that contain a null value in the from field will be rejected instead of setting the field’s value
+to null.
whether a one-time mutation of the field value is allowed from
+null to a non-null value. This can be useful when dealing with a field that may not have a value
+on all source events. For example, if the source field was not initially part of the schema of your
+source dataset, you may have old records that lack a value for this field. When set, this option
+allows a one-time mutation of the field value from null to a non-null value. Once set to a
+non-null value, any additional null values that are encountered will be ignored (ensuring that
+the indexed data converges on the same state regardless of the order the events are ingested in).
+Note: this option cannot be enabled when nullable: false has been set.
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/indexing/derived_indexed_type.rb', line 174
+
+defimmutable_value(field_name,from:,nullable:true,can_change_from_null:false)
+ if!nullable&&can_change_from_null
+ raiseErrors::SchemaError,"`can_change_from_null: true` is not allowed with `nullable: false` (as there would be no `null` values to change from)."
+ end
+
+ fields<<DerivedFields::ImmutableValue.new(
+ destination_field:field_name,
+ source_field:from,
+ nullable:nullable,
+ can_change_from_null:can_change_from_null
+ )
+end
+ This constant is part of a private API.
+ You should avoid using this constant if possible, as it may be removed or be changed in the future.
+
+
+
+ Note:
+
We don’t handle integer here because it’s the default numeric type (handled by our definition of the Int scalar type).
+
+
+
+
+ Note:
+
Likewise, we don’t handle long here because a custom scalar type must be used for that since GraphQL’s Int type can’t handle long values.
+
+
+
+
JSON schema overrides that automatically apply to specific mapping types so that the JSON schema
+validation will reject values which cannot be indexed into fields of a specific mapping type.
Builds a hash containing the mapping for the provided fields, normalizing it in the same way that the datastore does so that consistency checks between our index configuration and what’s in the datastore work properly.
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
Builds a hash containing the mapping for the provided fields, normalizing it in the same way that the
+datastore does so that consistency checks between our index configuration and what’s in the datastore
+work properly.
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/indexing/field.rb', line 87
+
+defself.normalized_mapping_hash_for(fields)
+ # When an object field has `properties`, the datastore normalizes the mapping by dropping
+# the `type => object` (it's implicit, as `properties` are only valid on an object...).
+# OTOH, when there are no properties, the datastore normalizes the mapping by dropping the
+# empty `properties` entry and instead returning `type => object`.
+return{"type"=>"object"}iffields.empty?
+
+ # Partition the fields into runtime fields and normal fields based on the presence of runtime_script
+runtime_fields,normal_fields=fields.partition(&:runtime_field_script)
+
+ mapping_hash={
+ "properties"=>normal_fields.to_h{|f|[f.name_in_index,f.mapping]}
+ }
+ unlessruntime_fields.empty?
+ mapping_hash["runtime"]=runtime_fields.to_hdo|f|
+ [f.name_in_index,f.mapping.merge({"script"=>{"source"=>f.runtime_field_script}})]
+ end
+ end
+
+ mapping_hash
+end
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
Returns the JSON schema definition for this field. The returned object should
+be composed entirely of Ruby primitives that, when converted to a JSON string, match the
+requirements of the JSON schema spec.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Hash<String, Object>)
+
+
+
+ —
+
the JSON schema definition for this field. The returned object should
+be composed entirely of Ruby primitives that, when converted to a JSON string, match the
+requirements of the JSON schema spec.
+
+
+
+
+
+
+
+
+
+
+
+
+68
+69
+70
+71
+72
+73
+74
+
+
+
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/indexing/field.rb', line 68
+
+defjson_schema
+ json_schema_layers
+ .reverse# resolve layers from innermost to outermost wrappings
+.reduce(inner_json_schema){|acc,layer|process_layer(layer,acc)}
+ .merge(outer_json_schema_customizations)
+ .then{|h|Support::HashUtil.stringify_keys(h)}
+end
additional ElasticGraph metadata to be stored in the JSON schema for this field.
+
+
+
+
+
+
+
+
+
+
+
+
+77
+78
+79
+
+
+
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/indexing/field.rb', line 77
+
+defjson_schema_metadata
+ JSONSchemaFieldMetadata.new(type:type.name,name_in_index:name_in_index)
+end
+
+
+
+
+
+
+
+
+ #mapping ⇒ Hash<String, Object>
+
+
+
+
+
+
+
+
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
Returns the mapping for this field. The returned hash should be composed entirely
+of Ruby primitives that, when converted to a JSON string, match the structure required by
+Elasticsearch.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Hash<String, Object>)
+
+
+
+ —
+
the mapping for this field. The returned hash should be composed entirely
+of Ruby primitives that, when converted to a JSON string, match the structure required by
+Elasticsearch.
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/indexing/field.rb', line 49
+
+defmapping
+ @mapping||=begin
+ raw_mapping=indexing_field_type
+ .to_mapping
+ .merge(Support::HashUtil.stringify_keys(mapping_customizations))
+
+ if(object_type=type.fully_unwrapped.as_object_type)&&type.list?&&mapping_customizations[:type]=="nested"
+ # If it's an object list field using the `nested` type, we need to add a `__counts` field to
+# the mapping for all of its subfields which are lists.
+ListCountsMapping.merged_into(raw_mapping,for_type:object_type)
+ else
+ raw_mapping
+ end
+ end
+end
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/main/ElasticGraph/SchemaDefinition/Indexing/FieldReference.html b/docs/main/ElasticGraph/SchemaDefinition/Indexing/FieldReference.html
new file mode 100644
index 00000000..8bac3c6d
--- /dev/null
+++ b/docs/main/ElasticGraph/SchemaDefinition/Indexing/FieldReference.html
@@ -0,0 +1,268 @@
+
+
+
+
+
+
+ Class: ElasticGraph::SchemaDefinition::Indexing::FieldReference
+
+ — Documentation by YARD 0.9.37
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This class is part of a private API.
+ You should avoid using this class if possible, as it may be removed or be changed in the future.
+
+
A lazy reference to a Field. It contains all attributes needed to build a Field, but the referenced type may not be
+resolvable yet (which is why this exists).
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/indexing/field_type/enum.rb', line 25
+
+classEnum<::Data
+ # @return [Hash<String, ::Object>] the JSON schema for this enum type.
+defto_json_schema
+ {"type"=>"string","enum"=>enum_value_names}
+ end
+
+ # @return [Hash<String, ::Object>] the datastore mapping for this enum type.
+defto_mapping
+ {"type"=>"keyword"}
+ end
+
+ # @return [Hash<String, ::Object>] additional ElasticGraph metadata to put in the JSON schema for this enum type.
+defjson_schema_field_metadata_by_field_name
+ {}
+ end
+
+ # @param customizations [Hash<String, ::Object>] JSON schema customizations
+# @return [Hash<String, ::Object>] formatted customizations.
+defformat_field_json_schema_customizations(customizations)
+ # Since an enum type already restricts the values to a small set of allowed values, we do not need to keep
+# other customizations (such as the `maxLength` field customization EG automatically applies to fields
+# indexed as a `keyword`--we don't allow enum values to exceed that length, anyway).
+#
+# It's desirable to restrict what customizations are applied because when a publisher uses the JSON schema
+# to generate code using a library such as https://github.com/pwall567/json-kotlin-schema-codegen, we found
+# that the presence of extra field customizations inhibits the library's ability to generate code in the way
+# we want (it causes the type of the enum to change since the JSON schema changes from a direct `$ref` to
+# being wrapped in an `allOf`).
+#
+# However, we still want to apply `enum` customizations--this allows a user to "narrow" the set of allowed
+# values for a field. For example, a `Currency` enum could contain every currency, and a user may want to
+# restrict a specific `currency` field to a subset of currencies (e.g. to just USD, CAD, and EUR).
+customizations.slice("enum")
+ end
+
+ # @dynamic initialize, enum_value_names
+end
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/indexing/field_type/enum.rb', line 43
+
+defformat_field_json_schema_customizations(customizations)
+ # Since an enum type already restricts the values to a small set of allowed values, we do not need to keep
+# other customizations (such as the `maxLength` field customization EG automatically applies to fields
+# indexed as a `keyword`--we don't allow enum values to exceed that length, anyway).
+#
+# It's desirable to restrict what customizations are applied because when a publisher uses the JSON schema
+# to generate code using a library such as https://github.com/pwall567/json-kotlin-schema-codegen, we found
+# that the presence of extra field customizations inhibits the library's ability to generate code in the way
+# we want (it causes the type of the enum to change since the JSON schema changes from a direct `$ref` to
+# being wrapped in an `allOf`).
+#
+# However, we still want to apply `enum` customizations--this allows a user to "narrow" the set of allowed
+# values for a field. For example, a `Currency` enum could contain every currency, and a user may want to
+# restrict a specific `currency` field to a subset of currencies (e.g. to just USD, CAD, and EUR).
+customizations.slice("enum")
+end
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/indexing/field_type/object.rb', line 29
+
+classObject<Support::MemoizableData.define(:type_name,:subfields,:mapping_options,:json_schema_options)
+ # @return [Hash<String, ::Object>] the datastore mapping for this object type.
+defto_mapping
+ @to_mapping||=begin
+ base_mapping=Field.normalized_mapping_hash_for(subfields)
+ # When a custom mapping type is used, we need to omit `properties`, because custom mapping
+# types generally don't use `properties` (and if you need to use `properties` with a custom
+# type, you're responsible for defining the properties).
+base_mapping=base_mapping.except("properties")if(mapping_options[:type]||"object")!="object"
+ base_mapping.merge(Support::HashUtil.stringify_keys(mapping_options))
+ end
+ end
+
+ # @return [Hash<String, ::Object>] the JSON schema for this object type.
+defto_json_schema
+ @to_json_schema||=
+ ifjson_schema_options.empty?
+ # Fields that are `sourced_from` an alternate type must not be included in this types JSON schema,
+# since events of this type won't include them.
+other_source_subfields,json_schema_candidate_subfields=subfields.partition(&:source)
+ validate_sourced_fields_have_no_json_schema_overrides(other_source_subfields)
+ json_schema_subfields=json_schema_candidate_subfields.reject(&:runtime_field_script)
+
+ {
+ "type"=>"object",
+ "properties"=>json_schema_subfields.to_h{|f|[f.name,f.json_schema]}.merge(json_schema_typename_field),
+ # Note: `__typename` is intentionally not included in the `required` list. If `__typename` is present
+# we want it validated (as we do by merging in `json_schema_typename_field`) but we only want
+# to require it in the context of a union type. The union's json schema requires the field.
+"required"=>json_schema_subfields.map(&:name).freeze
+ }.freeze
+ else
+ Support::HashUtil.stringify_keys(json_schema_options)
+ end
+ end
+
+ # @return [Hash<String, ::Object>] additional ElasticGraph metadata to put in the JSON schema for this object type.
+defjson_schema_field_metadata_by_field_name
+ subfields.to_h{|f|[f.name,f.json_schema_metadata]}
+ end
+
+ # @param customizations [Hash<String, ::Object>] JSON schema customizations
+# @return [Hash<String, ::Object>] formatted customizations.
+defformat_field_json_schema_customizations(customizations)
+ customizations
+ end
+
+ private
+
+ defafter_initialize
+ subfields.freeze
+ end
+
+ # Returns a __typename property which we use for union types.
+#
+# This must always be set to the name of the type (thus the const value).
+#
+# We also add a "default" value. This does not impact validation, but rather
+# aids tools like our kotlin codegen to save publishers from having to set the
+# property explicitly when creating events.
+defjson_schema_typename_field
+ {
+ "__typename"=>{
+ "type"=>"string",
+ "const"=>type_name,
+ "default"=>type_name
+ }
+ }
+ end
+
+ defvalidate_sourced_fields_have_no_json_schema_overrides(other_source_subfields)
+ problem_fields=other_source_subfields.reject{|f|f.json_schema_customizations.empty?}
+ returnifproblem_fields.empty?
+
+ field_descriptions=problem_fields.map(&:name).sort.map{|f|"`#{f}`"}.join(", ")
+ raiseErrors::SchemaError,
+ "`#{type_name}` has #{problem_fields.size} field(s) (#{field_descriptions}) that are `sourced_from` " \
+ "another type and also have JSON schema customizations. Instead, put the JSON schema " \
+ "customizations on the source type's field definitions."
+ end
+end
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/indexing/field_type/object.rb', line 29
+
+classObject<Support::MemoizableData.define(:type_name,:subfields,:mapping_options,:json_schema_options)
+ # @return [Hash<String, ::Object>] the datastore mapping for this object type.
+defto_mapping
+ @to_mapping||=begin
+ base_mapping=Field.normalized_mapping_hash_for(subfields)
+ # When a custom mapping type is used, we need to omit `properties`, because custom mapping
+# types generally don't use `properties` (and if you need to use `properties` with a custom
+# type, you're responsible for defining the properties).
+base_mapping=base_mapping.except("properties")if(mapping_options[:type]||"object")!="object"
+ base_mapping.merge(Support::HashUtil.stringify_keys(mapping_options))
+ end
+ end
+
+ # @return [Hash<String, ::Object>] the JSON schema for this object type.
+defto_json_schema
+ @to_json_schema||=
+ ifjson_schema_options.empty?
+ # Fields that are `sourced_from` an alternate type must not be included in this types JSON schema,
+# since events of this type won't include them.
+other_source_subfields,json_schema_candidate_subfields=subfields.partition(&:source)
+ validate_sourced_fields_have_no_json_schema_overrides(other_source_subfields)
+ json_schema_subfields=json_schema_candidate_subfields.reject(&:runtime_field_script)
+
+ {
+ "type"=>"object",
+ "properties"=>json_schema_subfields.to_h{|f|[f.name,f.json_schema]}.merge(json_schema_typename_field),
+ # Note: `__typename` is intentionally not included in the `required` list. If `__typename` is present
+# we want it validated (as we do by merging in `json_schema_typename_field`) but we only want
+# to require it in the context of a union type. The union's json schema requires the field.
+"required"=>json_schema_subfields.map(&:name).freeze
+ }.freeze
+ else
+ Support::HashUtil.stringify_keys(json_schema_options)
+ end
+ end
+
+ # @return [Hash<String, ::Object>] additional ElasticGraph metadata to put in the JSON schema for this object type.
+defjson_schema_field_metadata_by_field_name
+ subfields.to_h{|f|[f.name,f.json_schema_metadata]}
+ end
+
+ # @param customizations [Hash<String, ::Object>] JSON schema customizations
+# @return [Hash<String, ::Object>] formatted customizations.
+defformat_field_json_schema_customizations(customizations)
+ customizations
+ end
+
+ private
+
+ defafter_initialize
+ subfields.freeze
+ end
+
+ # Returns a __typename property which we use for union types.
+#
+# This must always be set to the name of the type (thus the const value).
+#
+# We also add a "default" value. This does not impact validation, but rather
+# aids tools like our kotlin codegen to save publishers from having to set the
+# property explicitly when creating events.
+defjson_schema_typename_field
+ {
+ "__typename"=>{
+ "type"=>"string",
+ "const"=>type_name,
+ "default"=>type_name
+ }
+ }
+ end
+
+ defvalidate_sourced_fields_have_no_json_schema_overrides(other_source_subfields)
+ problem_fields=other_source_subfields.reject{|f|f.json_schema_customizations.empty?}
+ returnifproblem_fields.empty?
+
+ field_descriptions=problem_fields.map(&:name).sort.map{|f|"`#{f}`"}.join(", ")
+ raiseErrors::SchemaError,
+ "`#{type_name}` has #{problem_fields.size} field(s) (#{field_descriptions}) that are `sourced_from` " \
+ "another type and also have JSON schema customizations. Instead, put the JSON schema " \
+ "customizations on the source type's field definitions."
+ end
+end
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/indexing/field_type/object.rb', line 29
+
+classObject<Support::MemoizableData.define(:type_name,:subfields,:mapping_options,:json_schema_options)
+ # @return [Hash<String, ::Object>] the datastore mapping for this object type.
+defto_mapping
+ @to_mapping||=begin
+ base_mapping=Field.normalized_mapping_hash_for(subfields)
+ # When a custom mapping type is used, we need to omit `properties`, because custom mapping
+# types generally don't use `properties` (and if you need to use `properties` with a custom
+# type, you're responsible for defining the properties).
+base_mapping=base_mapping.except("properties")if(mapping_options[:type]||"object")!="object"
+ base_mapping.merge(Support::HashUtil.stringify_keys(mapping_options))
+ end
+ end
+
+ # @return [Hash<String, ::Object>] the JSON schema for this object type.
+defto_json_schema
+ @to_json_schema||=
+ ifjson_schema_options.empty?
+ # Fields that are `sourced_from` an alternate type must not be included in this types JSON schema,
+# since events of this type won't include them.
+other_source_subfields,json_schema_candidate_subfields=subfields.partition(&:source)
+ validate_sourced_fields_have_no_json_schema_overrides(other_source_subfields)
+ json_schema_subfields=json_schema_candidate_subfields.reject(&:runtime_field_script)
+
+ {
+ "type"=>"object",
+ "properties"=>json_schema_subfields.to_h{|f|[f.name,f.json_schema]}.merge(json_schema_typename_field),
+ # Note: `__typename` is intentionally not included in the `required` list. If `__typename` is present
+# we want it validated (as we do by merging in `json_schema_typename_field`) but we only want
+# to require it in the context of a union type. The union's json schema requires the field.
+"required"=>json_schema_subfields.map(&:name).freeze
+ }.freeze
+ else
+ Support::HashUtil.stringify_keys(json_schema_options)
+ end
+ end
+
+ # @return [Hash<String, ::Object>] additional ElasticGraph metadata to put in the JSON schema for this object type.
+defjson_schema_field_metadata_by_field_name
+ subfields.to_h{|f|[f.name,f.json_schema_metadata]}
+ end
+
+ # @param customizations [Hash<String, ::Object>] JSON schema customizations
+# @return [Hash<String, ::Object>] formatted customizations.
+defformat_field_json_schema_customizations(customizations)
+ customizations
+ end
+
+ private
+
+ defafter_initialize
+ subfields.freeze
+ end
+
+ # Returns a __typename property which we use for union types.
+#
+# This must always be set to the name of the type (thus the const value).
+#
+# We also add a "default" value. This does not impact validation, but rather
+# aids tools like our kotlin codegen to save publishers from having to set the
+# property explicitly when creating events.
+defjson_schema_typename_field
+ {
+ "__typename"=>{
+ "type"=>"string",
+ "const"=>type_name,
+ "default"=>type_name
+ }
+ }
+ end
+
+ defvalidate_sourced_fields_have_no_json_schema_overrides(other_source_subfields)
+ problem_fields=other_source_subfields.reject{|f|f.json_schema_customizations.empty?}
+ returnifproblem_fields.empty?
+
+ field_descriptions=problem_fields.map(&:name).sort.map{|f|"`#{f}`"}.join(", ")
+ raiseErrors::SchemaError,
+ "`#{type_name}` has #{problem_fields.size} field(s) (#{field_descriptions}) that are `sourced_from` " \
+ "another type and also have JSON schema customizations. Instead, put the JSON schema " \
+ "customizations on the source type's field definitions."
+ end
+end
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/indexing/field_type/object.rb', line 29
+
+classObject<Support::MemoizableData.define(:type_name,:subfields,:mapping_options,:json_schema_options)
+ # @return [Hash<String, ::Object>] the datastore mapping for this object type.
+defto_mapping
+ @to_mapping||=begin
+ base_mapping=Field.normalized_mapping_hash_for(subfields)
+ # When a custom mapping type is used, we need to omit `properties`, because custom mapping
+# types generally don't use `properties` (and if you need to use `properties` with a custom
+# type, you're responsible for defining the properties).
+base_mapping=base_mapping.except("properties")if(mapping_options[:type]||"object")!="object"
+ base_mapping.merge(Support::HashUtil.stringify_keys(mapping_options))
+ end
+ end
+
+ # @return [Hash<String, ::Object>] the JSON schema for this object type.
+defto_json_schema
+ @to_json_schema||=
+ ifjson_schema_options.empty?
+ # Fields that are `sourced_from` an alternate type must not be included in this types JSON schema,
+# since events of this type won't include them.
+other_source_subfields,json_schema_candidate_subfields=subfields.partition(&:source)
+ validate_sourced_fields_have_no_json_schema_overrides(other_source_subfields)
+ json_schema_subfields=json_schema_candidate_subfields.reject(&:runtime_field_script)
+
+ {
+ "type"=>"object",
+ "properties"=>json_schema_subfields.to_h{|f|[f.name,f.json_schema]}.merge(json_schema_typename_field),
+ # Note: `__typename` is intentionally not included in the `required` list. If `__typename` is present
+# we want it validated (as we do by merging in `json_schema_typename_field`) but we only want
+# to require it in the context of a union type. The union's json schema requires the field.
+"required"=>json_schema_subfields.map(&:name).freeze
+ }.freeze
+ else
+ Support::HashUtil.stringify_keys(json_schema_options)
+ end
+ end
+
+ # @return [Hash<String, ::Object>] additional ElasticGraph metadata to put in the JSON schema for this object type.
+defjson_schema_field_metadata_by_field_name
+ subfields.to_h{|f|[f.name,f.json_schema_metadata]}
+ end
+
+ # @param customizations [Hash<String, ::Object>] JSON schema customizations
+# @return [Hash<String, ::Object>] formatted customizations.
+defformat_field_json_schema_customizations(customizations)
+ customizations
+ end
+
+ private
+
+ defafter_initialize
+ subfields.freeze
+ end
+
+ # Returns a __typename property which we use for union types.
+#
+# This must always be set to the name of the type (thus the const value).
+#
+# We also add a "default" value. This does not impact validation, but rather
+# aids tools like our kotlin codegen to save publishers from having to set the
+# property explicitly when creating events.
+defjson_schema_typename_field
+ {
+ "__typename"=>{
+ "type"=>"string",
+ "const"=>type_name,
+ "default"=>type_name
+ }
+ }
+ end
+
+ defvalidate_sourced_fields_have_no_json_schema_overrides(other_source_subfields)
+ problem_fields=other_source_subfields.reject{|f|f.json_schema_customizations.empty?}
+ returnifproblem_fields.empty?
+
+ field_descriptions=problem_fields.map(&:name).sort.map{|f|"`#{f}`"}.join(", ")
+ raiseErrors::SchemaError,
+ "`#{type_name}` has #{problem_fields.size} field(s) (#{field_descriptions}) that are `sourced_from` " \
+ "another type and also have JSON schema customizations. Instead, put the JSON schema " \
+ "customizations on the source type's field definitions."
+ end
+end
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/indexing/field_type/object.rb', line 43
+
+defto_json_schema
+ @to_json_schema||=
+ ifjson_schema_options.empty?
+ # Fields that are `sourced_from` an alternate type must not be included in this types JSON schema,
+# since events of this type won't include them.
+other_source_subfields,json_schema_candidate_subfields=subfields.partition(&:source)
+ validate_sourced_fields_have_no_json_schema_overrides(other_source_subfields)
+ json_schema_subfields=json_schema_candidate_subfields.reject(&:runtime_field_script)
+
+ {
+ "type"=>"object",
+ "properties"=>json_schema_subfields.to_h{|f|[f.name,f.json_schema]}.merge(json_schema_typename_field),
+ # Note: `__typename` is intentionally not included in the `required` list. If `__typename` is present
+# we want it validated (as we do by merging in `json_schema_typename_field`) but we only want
+# to require it in the context of a union type. The union's json schema requires the field.
+"required"=>json_schema_subfields.map(&:name).freeze
+ }.freeze
+ else
+ Support::HashUtil.stringify_keys(json_schema_options)
+ end
+end
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
Returns the datastore mapping for this object type.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Hash<String, ::Object>)
+
+
+
+ —
+
the datastore mapping for this object type.
+
+
+
+
+
+
+
+
+
+
+
+
+31
+32
+33
+34
+35
+36
+37
+38
+39
+40
+
+
+
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/indexing/field_type/object.rb', line 31
+
+defto_mapping
+ @to_mapping||=begin
+ base_mapping=Field.normalized_mapping_hash_for(subfields)
+ # When a custom mapping type is used, we need to omit `properties`, because custom mapping
+# types generally don't use `properties` (and if you need to use `properties` with a custom
+# type, you're responsible for defining the properties).
+base_mapping=base_mapping.except("properties")if(mapping_options[:type]||"object")!="object"
+ base_mapping.merge(Support::HashUtil.stringify_keys(mapping_options))
+ end
+end
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/main/ElasticGraph/SchemaDefinition/Indexing/FieldType/Scalar.html b/docs/main/ElasticGraph/SchemaDefinition/Indexing/FieldType/Scalar.html
new file mode 100644
index 00000000..be5659ad
--- /dev/null
+++ b/docs/main/ElasticGraph/SchemaDefinition/Indexing/FieldType/Scalar.html
@@ -0,0 +1,651 @@
+
+
+
+
+
+
+ Class: ElasticGraph::SchemaDefinition::Indexing::FieldType::Scalar
+
+ — Documentation by YARD 0.9.37
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/indexing/field_type/union.rb', line 26
+
+classUnion<::Data.define(:subtypes_by_name)
+ # @return [Hash<String, ::Object>] the JSON schema for this union type.
+defto_json_schema
+ subtype_json_schemas=subtypes_by_name.keys.map{|name|{"$ref"=>"#/$defs/#{name}"}}
+
+ # A union type can represent multiple subtypes, referenced by the "anyOf" clause below.
+# We also add a requirement for the presence of __typename to indicate which type
+# is being referenced (this property is pre-defined on the type itself as a constant).
+#
+# Note: Although both "oneOf" and "anyOf" keywords are valid for combining schemas
+# to form a union, and validate equivalently when no object can satisfy multiple of the
+# subschemas (which is the case here given the __typename requirements are mutually
+# exclusive), we chose to use "oneOf" here because it works better with this library:
+# https://github.com/pwall567/json-kotlin-schema-codegen
+{
+ "required"=>%w[__typename],
+ "oneOf"=>subtype_json_schemas
+ }
+ end
+
+ # @return [Hash<String, ::Object>] the datastore mapping for this union type.
+defto_mapping
+ mapping_subfields=subtypes_by_name.values.map(&:subfields).reduce([],:union)
+
+ Support::HashUtil.deep_merge(
+ Field.normalized_mapping_hash_for(mapping_subfields),
+ {"properties"=>{"__typename"=>{"type"=>"keyword"}}}
+ )
+ end
+
+ # @return [Hash<String, ::Object>] additional ElasticGraph metadata to put in the JSON schema for this union type.
+defjson_schema_field_metadata_by_field_name
+ {}
+ end
+
+ # @param customizations [Hash<String, ::Object>] JSON schema customizations
+# @return [Hash<String, ::Object>] formatted customizations.
+defformat_field_json_schema_customizations(customizations)
+ customizations
+ end
+end
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/indexing/field_type/union.rb', line 28
+
+defto_json_schema
+ subtype_json_schemas=subtypes_by_name.keys.map{|name|{"$ref"=>"#/$defs/#{name}"}}
+
+ # A union type can represent multiple subtypes, referenced by the "anyOf" clause below.
+# We also add a requirement for the presence of __typename to indicate which type
+# is being referenced (this property is pre-defined on the type itself as a constant).
+#
+# Note: Although both "oneOf" and "anyOf" keywords are valid for combining schemas
+# to form a union, and validate equivalently when no object can satisfy multiple of the
+# subschemas (which is the case here given the __typename requirements are mutually
+# exclusive), we chose to use "oneOf" here because it works better with this library:
+# https://github.com/pwall567/json-kotlin-schema-codegen
+{
+ "required"=>%w[__typename],
+ "oneOf"=>subtype_json_schemas
+ }
+end
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/indexing/index.rb', line 48
+
+definitialize(name,settings,schema_def_state,indexed_type)
+ ifname.include?(ROLLOVER_INDEX_INFIX_MARKER)
+ raiseErrors::SchemaError,"`#{name}` is an invalid index definition name since it contains " \
+ "`#{ROLLOVER_INDEX_INFIX_MARKER}` which ElasticGraph treats as special."
+ end
+
+ settings=DEFAULT_SETTINGS.merge(Support::HashUtil.flatten_and_stringify_keys(settings,prefix:"index"))
+
+ super(name,[],settings,schema_def_state,indexed_type,[],nil)
+
+ # `id` is the field Elasticsearch/OpenSearch use for routing by default:
+# https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-routing-field.html
+# By using it here, it will cause queries to pass a `routing` parameter when
+# searching with id filtering on an index that does not use custom shard routing, giving
+# us a nice efficiency boost.
+self.routing_field_path=public_field_path("id",explanation:"indexed types must have an `id` field")
+
+ yieldselfifblock_given?
+end
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/indexing/index.rb', line 39
+
+classIndex<Struct.new(:name,:default_sort_pairs,:settings,:schema_def_state,:indexed_type,:routing_field_path,:rollover_config)
+ includeMixins::HasReadableToSAndInspect.new{|i|i.name}
+
+ # @param name [String] name of the index
+# @param settings [Hash<(String, Object)>] datastore settings for the index
+# @param schema_def_state [State] schema definition state
+# @param indexed_type [SchemaElements::ObjectType, SchemaElements::InterfaceType, SchemaElements::UnionType] type backed by this index
+# @yield [Index] the index, for further customization
+# @api private
+definitialize(name,settings,schema_def_state,indexed_type)
+ ifname.include?(ROLLOVER_INDEX_INFIX_MARKER)
+ raiseErrors::SchemaError,"`#{name}` is an invalid index definition name since it contains " \
+ "`#{ROLLOVER_INDEX_INFIX_MARKER}` which ElasticGraph treats as special."
+ end
+
+ settings=DEFAULT_SETTINGS.merge(Support::HashUtil.flatten_and_stringify_keys(settings,prefix:"index"))
+
+ super(name,[],settings,schema_def_state,indexed_type,[],nil)
+
+ # `id` is the field Elasticsearch/OpenSearch use for routing by default:
+# https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-routing-field.html
+# By using it here, it will cause queries to pass a `routing` parameter when
+# searching with id filtering on an index that does not use custom shard routing, giving
+# us a nice efficiency boost.
+self.routing_field_path=public_field_path("id",explanation:"indexed types must have an `id` field")
+
+ yieldselfifblock_given?
+ end
+
+ # Specifies how documents in this index should sort by default, when no `orderBy` argument is provided to the GraphQL query.
+#
+# @note the field name strings can be a dot-separated nested fields, but all referenced
+# fields must exist when this is called.
+#
+# @param field_name_direction_pairs [Array<(String, Symbol)>] pairs of field names and `:asc` or `:desc`
+# @return [void]
+#
+# @example Sort on `name` (ascending) with `createdAt` (descending) as a tie-breaker
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Campaign" do |t|
+# t.field "id", "ID!"
+# t.field "name", "String"
+# t.field "createdAt", "DateTime"
+#
+# t.index "campaigns"do |i|
+# i.default_sort "name", :asc, "createdAt", :desc
+# end
+# end
+# end
+defdefault_sort(*field_name_direction_pairs)
+ self.default_sort_pairs=field_name_direction_pairs
+ end
+
+ # Causes this index to "rollover" at the provided `frequency` based on the value of the provided `timestamp_field_path_name`.
+# This is particularly useful for time-series data. Partitioning the data into `hourly`, `daily`, `monthly` or `yearly` buckets
+# allows for different index configurations, and can be necessary when a dataset is too large to fit in one dataset given
+# Elasticsearch/OpenSearch limitations on the number of shards in one index. In addition, ElasticGraph optimizes queries which
+# filter on the timestamp field to target the subset of the indices in which matching documents could reside.
+#
+# @note the timestamp field specified here **must be immutable**. To understand why, consider a `:yearly` rollover
+# index used for data based on `createdAt`; if ElasticGraph ingests record `123` with a createdAt of `2023-12-31T23:59:59Z`, it
+# will be indexed in the `2023` index. Later if it receives an update event for record `123` with a `createdAt` of
+# `2024-01-01T00:00:00Z` (a mere one second later!), ElasticGraph will store the new version of the payment in the `2024` index,
+# and leave the old copy of the payment in the `2023` index unchanged. It’ll have duplicates for that document.
+# @note changing the `rollover` configuration on an existing index that already has data will result in duplicate documents
+#
+# @param frequency [:yearly, :monthly, :daily, :hourly] how often to rollover the index
+# @param timestamp_field_path_name [String] dot-separated path to the timestamp field used for rollover. Note: all referenced
+# fields must exist when this is called.
+# @return [void]
+#
+# @example Define a `campaigns` index to rollover yearly based on `createdAt`
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Campaign" do |t|
+# t.field "id", "ID!"
+# t.field "name", "String"
+# t.field "createdAt", "DateTime"
+#
+# t.index "campaigns"do |i|
+# i.rollover :yearly, "createdAt"
+# end
+# end
+# end
+defrollover(frequency,timestamp_field_path_name)
+ timestamp_field_path=public_field_path(timestamp_field_path_name,explanation:"it is referenced as an index `rollover` field")
+
+ unlessdate_and_datetime_types.include?(timestamp_field_path.type.fully_unwrapped.name)
+ date_or_datetime_description=date_and_datetime_types.map{|t|"`#{t}`"}.join(" or ")
+ raiseErrors::SchemaError,"rollover field `#{timestamp_field_path.full_description}` cannot be used for rollover since it is not a #{date_or_datetime_description} field."
+ end
+
+ iftimestamp_field_path.type.list?
+ raiseErrors::SchemaError,"rollover field `#{timestamp_field_path.full_description}` cannot be used for rollover since it is a list field."
+ end
+
+ timestamp_field_path.path_parts.each{|f|f.json_schemanullable:false}
+
+ self.rollover_config=RolloverConfig.new(
+ frequency:frequency,
+ timestamp_field_path:timestamp_field_path
+ )
+ end
+
+ # Configures the index to [route documents to shards](https://www.elastic.co/guide/en/elasticsearch/reference/8.15/mapping-routing-field.html)
+# based on the specified field. ElasticGraph optimizes queries that filter on the shard routing field so that they only run on a
+# subset of nodes instead of all nodes. This can make a big difference in query performance if queries usually filter on a certain
+# field. Using an appropriate field for shard routing is often essential for horizontal scaling, as it avoids having every query
+# hit every node, allowing additional nodes to increase query throughput.
+#
+# @note it is essential that the shards are well-balanced. If the data’s distribution is lopsided, using this feature can make
+# performance worse.
+# @note the routing field specified here **must be immutable**. If ElasticGraph receives an updated version of a document with a
+# different routing value, it’ll write the new version of the document to a different shard and leave the copy on the old shard
+# unchanged, leading to duplicates.
+# @note changing the shard routing configuration on an existing index that already has data will result in duplicate documents
+#
+# @param routing_field_path_name [String] dot-separated path to the field used for shard routing. Note: all referenced
+# fields must exist when this is called.
+# @return [void]
+#
+# @example Define a `campaigns` index to shard on `organizationId`
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Campaign" do |t|
+# t.field "id", "ID!"
+# t.field "name", "String"
+# t.field "organizationId", "ID"
+#
+# t.index "campaigns"do |i|
+# i.route_with "organizationId"
+# end
+# end
+# end
+defroute_with(routing_field_path_name)
+ routing_field_path=public_field_path(routing_field_path_name,explanation:"it is referenced as an index `route_with` field")
+
+ unlessrouting_field_path.type.leaf?
+ raiseErrors::SchemaError,"shard routing field `#{routing_field_path.full_description}` cannot be used for routing since it is not a leaf field."
+ end
+
+ self.routing_field_path=routing_field_path
+
+ routing_field_path.path_parts[0..-2].each{|f|f.json_schemanullable:false}
+ routing_field_path.last_part.json_schemanullable:false,pattern:HAS_NON_WHITE_SPACE_REGEX
+ indexed_type.append_to_documentation"For more performant queries on this type, please filter on `#{routing_field_path_name}` if possible."
+ end
+
+ # @see #route_with
+# @return [Boolean] whether or not this index uses custom shard routing
+defuses_custom_routing?
+ routing_field_path.path_in_index!="id"
+ end
+
+ # @return [Hash<String, Object>] datastore configuration for this index for when it does not use rollover
+defto_index_config
+ {
+ "aliases"=>{},
+ "mappings"=>mappings,
+ "settings"=>settings
+ }.compact
+ end
+
+ # @return [Hash<String, Object>] datastore configuration for the index template that will be defined if rollover is used
+defto_index_template_config
+ {
+ "index_patterns"=>["#{name}#{ROLLOVER_INDEX_INFIX_MARKER}*"],
+ "template"=>{
+ "aliases"=>{},
+ "mappings"=>mappings,
+ "settings"=>settings
+ }
+ }
+ end
+
+ # @return [SchemaArtifacts::RuntimeMetadata::IndexDefinition] runtime metadata for this index
+defruntime_metadata
+ SchemaArtifacts::RuntimeMetadata::IndexDefinition.new(
+ route_with:routing_field_path.path_in_index,
+ rollover:rollover_config&.runtime_metadata,
+ current_sources:indexed_type.current_sources,
+ fields_by_path:indexed_type.index_field_runtime_metadata_tuples.to_h,
+ default_sort_fields:default_sort_pairs.each_slice(2).mapdo|(graphql_field_path_name,direction)|
+ SchemaArtifacts::RuntimeMetadata::SortField.new(
+ field_path:public_field_path(graphql_field_path_name,explanation:"it is referenced as an index `default_sort` field").path_in_index,
+ direction:direction
+ )
+ end
+ )
+ end
+
+ private
+
+ # A regex that requires at least one non-whitespace character.
+# Note: this does not use the `/S` character class because it's recommended to use a small subset
+# of Regex syntax:
+#
+# > The regular expression syntax used is from JavaScript (ECMA 262, specifically). However, that
+# > complete syntax is not widely supported, therefore it is recommended that you stick to the subset
+# > of that syntax described below.
+#
+# (From https://json-schema.org/understanding-json-schema/reference/regular_expressions.html)
+HAS_NON_WHITE_SPACE_REGEX="[^ \t\n]+"
+
+ DEFAULT_SETTINGS={
+ "index.mapping.ignore_malformed"=>false,
+ "index.mapping.coerce"=>false,
+ "index.number_of_replicas"=>1,
+ "index.number_of_shards"=>1
+ }
+
+ defmappings
+ field_mappings=indexed_type
+ .to_indexing_field_type
+ .to_mapping
+ .except("type")# `type` is invalid at the mapping root because it always has to be an object.
+.then{|mapping|ListCountsMapping.merged_into(mapping,for_type:indexed_type)}
+ .thendo|fm|
+ Support::HashUtil.deep_merge(fm,{"properties"=>{
+ "__sources"=>{"type"=>"keyword"},
+ "__versions"=>{
+ "type"=>"object",
+ # __versions is map keyed by relationship name, with values that are maps keyed by id. Since it's not
+# a static object with known fields, we need to use dynamic here. Passing `false` allows some level
+# of dynamicness. As per https://www.elastic.co/guide/en/elasticsearch/reference/8.7/dynamic.html#dynamic-parameters:
+#
+# > New fields are ignored. These fields will not be indexed or searchable, but will still appear in the _source
+# > field of returned hits. These fields will not be added to the mapping, and new fields must be added explicitly.
+#
+# We need `__versions` to be in `_source` (so that our update scripts can operate on it), but
+# have no need for it to be searchable (as it's just an internal data structure used for indexing).
+#
+# Note: we intentionally set false as a string here, because that's how the datastore echoes it back
+# to us when you query the mapping (even if you set it as a boolean). Our checks for index mapping
+# consistency fail validation if we set it as a boolean since the datastore doesn't echo it back as
+# a boolean.
+"dynamic"=>"false"
+ }
+ }})
+ end
+
+ {"dynamic"=>"strict"}.merge(field_mappings).tapdo|hash|
+ # If we are using custom shard routing, we want to require a `routing` value to be provided
+# in every single index, get, delete or update request; otherwise the request might be
+# made against the wrong shard.
+hash["_routing"]={"required"=>true}ifuses_custom_routing?
+ hash["_size"]={"enabled"=>true}ifschema_def_state.index_document_sizes?
+ end
+ end
+
+ defpublic_field_path(public_path_string,explanation:)
+ parent_is_not_list=->(parent_field){!parent_field.type.list?}
+ resolver=SchemaElements::FieldPath::Resolver.new
+ resolved_path=resolver.resolve_public_path(indexed_type,public_path_string,&parent_is_not_list)
+ returnresolved_pathifresolved_path
+
+ path_parts=public_path_string.split(".")
+ error_msg="Field `#{indexed_type.name}.#{public_path_string}` cannot be resolved, but #{explanation}."
+
+ # If it is a nested field path, the problem could be that a type has been referenced which does not exist, so mention that.
+ifpath_parts.size>1
+ error_msg+=" Verify that all fields and types referenced by `#{public_path_string}` are defined."
+ end
+
+ # If the first part of the path doesn't resolve, the problem could be that the field is defined after the `index` call
+# but it needs to be defined before it, so mention that.
+ifresolver.resolve_public_path(indexed_type,path_parts.first,&parent_is_not_list).nil?
+ error_msg+=" Note: the `#{indexed_type.name}.#{path_parts.first}` definition must come before the `index` call."
+ end
+
+ raiseErrors::SchemaError,error_msg
+ end
+
+ defdate_and_datetime_types
+ @date_and_datetime_types||=%w[DateDateTime].mapdo|type|
+ schema_def_state.type_namer.name_for(type)
+ end
+ end
+end
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/indexing/index.rb', line 39
+
+classIndex<Struct.new(:name,:default_sort_pairs,:settings,:schema_def_state,:indexed_type,:routing_field_path,:rollover_config)
+ includeMixins::HasReadableToSAndInspect.new{|i|i.name}
+
+ # @param name [String] name of the index
+# @param settings [Hash<(String, Object)>] datastore settings for the index
+# @param schema_def_state [State] schema definition state
+# @param indexed_type [SchemaElements::ObjectType, SchemaElements::InterfaceType, SchemaElements::UnionType] type backed by this index
+# @yield [Index] the index, for further customization
+# @api private
+definitialize(name,settings,schema_def_state,indexed_type)
+ ifname.include?(ROLLOVER_INDEX_INFIX_MARKER)
+ raiseErrors::SchemaError,"`#{name}` is an invalid index definition name since it contains " \
+ "`#{ROLLOVER_INDEX_INFIX_MARKER}` which ElasticGraph treats as special."
+ end
+
+ settings=DEFAULT_SETTINGS.merge(Support::HashUtil.flatten_and_stringify_keys(settings,prefix:"index"))
+
+ super(name,[],settings,schema_def_state,indexed_type,[],nil)
+
+ # `id` is the field Elasticsearch/OpenSearch use for routing by default:
+# https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-routing-field.html
+# By using it here, it will cause queries to pass a `routing` parameter when
+# searching with id filtering on an index that does not use custom shard routing, giving
+# us a nice efficiency boost.
+self.routing_field_path=public_field_path("id",explanation:"indexed types must have an `id` field")
+
+ yieldselfifblock_given?
+ end
+
+ # Specifies how documents in this index should sort by default, when no `orderBy` argument is provided to the GraphQL query.
+#
+# @note the field name strings can be a dot-separated nested fields, but all referenced
+# fields must exist when this is called.
+#
+# @param field_name_direction_pairs [Array<(String, Symbol)>] pairs of field names and `:asc` or `:desc`
+# @return [void]
+#
+# @example Sort on `name` (ascending) with `createdAt` (descending) as a tie-breaker
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Campaign" do |t|
+# t.field "id", "ID!"
+# t.field "name", "String"
+# t.field "createdAt", "DateTime"
+#
+# t.index "campaigns"do |i|
+# i.default_sort "name", :asc, "createdAt", :desc
+# end
+# end
+# end
+defdefault_sort(*field_name_direction_pairs)
+ self.default_sort_pairs=field_name_direction_pairs
+ end
+
+ # Causes this index to "rollover" at the provided `frequency` based on the value of the provided `timestamp_field_path_name`.
+# This is particularly useful for time-series data. Partitioning the data into `hourly`, `daily`, `monthly` or `yearly` buckets
+# allows for different index configurations, and can be necessary when a dataset is too large to fit in one dataset given
+# Elasticsearch/OpenSearch limitations on the number of shards in one index. In addition, ElasticGraph optimizes queries which
+# filter on the timestamp field to target the subset of the indices in which matching documents could reside.
+#
+# @note the timestamp field specified here **must be immutable**. To understand why, consider a `:yearly` rollover
+# index used for data based on `createdAt`; if ElasticGraph ingests record `123` with a createdAt of `2023-12-31T23:59:59Z`, it
+# will be indexed in the `2023` index. Later if it receives an update event for record `123` with a `createdAt` of
+# `2024-01-01T00:00:00Z` (a mere one second later!), ElasticGraph will store the new version of the payment in the `2024` index,
+# and leave the old copy of the payment in the `2023` index unchanged. It’ll have duplicates for that document.
+# @note changing the `rollover` configuration on an existing index that already has data will result in duplicate documents
+#
+# @param frequency [:yearly, :monthly, :daily, :hourly] how often to rollover the index
+# @param timestamp_field_path_name [String] dot-separated path to the timestamp field used for rollover. Note: all referenced
+# fields must exist when this is called.
+# @return [void]
+#
+# @example Define a `campaigns` index to rollover yearly based on `createdAt`
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Campaign" do |t|
+# t.field "id", "ID!"
+# t.field "name", "String"
+# t.field "createdAt", "DateTime"
+#
+# t.index "campaigns"do |i|
+# i.rollover :yearly, "createdAt"
+# end
+# end
+# end
+defrollover(frequency,timestamp_field_path_name)
+ timestamp_field_path=public_field_path(timestamp_field_path_name,explanation:"it is referenced as an index `rollover` field")
+
+ unlessdate_and_datetime_types.include?(timestamp_field_path.type.fully_unwrapped.name)
+ date_or_datetime_description=date_and_datetime_types.map{|t|"`#{t}`"}.join(" or ")
+ raiseErrors::SchemaError,"rollover field `#{timestamp_field_path.full_description}` cannot be used for rollover since it is not a #{date_or_datetime_description} field."
+ end
+
+ iftimestamp_field_path.type.list?
+ raiseErrors::SchemaError,"rollover field `#{timestamp_field_path.full_description}` cannot be used for rollover since it is a list field."
+ end
+
+ timestamp_field_path.path_parts.each{|f|f.json_schemanullable:false}
+
+ self.rollover_config=RolloverConfig.new(
+ frequency:frequency,
+ timestamp_field_path:timestamp_field_path
+ )
+ end
+
+ # Configures the index to [route documents to shards](https://www.elastic.co/guide/en/elasticsearch/reference/8.15/mapping-routing-field.html)
+# based on the specified field. ElasticGraph optimizes queries that filter on the shard routing field so that they only run on a
+# subset of nodes instead of all nodes. This can make a big difference in query performance if queries usually filter on a certain
+# field. Using an appropriate field for shard routing is often essential for horizontal scaling, as it avoids having every query
+# hit every node, allowing additional nodes to increase query throughput.
+#
+# @note it is essential that the shards are well-balanced. If the data’s distribution is lopsided, using this feature can make
+# performance worse.
+# @note the routing field specified here **must be immutable**. If ElasticGraph receives an updated version of a document with a
+# different routing value, it’ll write the new version of the document to a different shard and leave the copy on the old shard
+# unchanged, leading to duplicates.
+# @note changing the shard routing configuration on an existing index that already has data will result in duplicate documents
+#
+# @param routing_field_path_name [String] dot-separated path to the field used for shard routing. Note: all referenced
+# fields must exist when this is called.
+# @return [void]
+#
+# @example Define a `campaigns` index to shard on `organizationId`
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Campaign" do |t|
+# t.field "id", "ID!"
+# t.field "name", "String"
+# t.field "organizationId", "ID"
+#
+# t.index "campaigns"do |i|
+# i.route_with "organizationId"
+# end
+# end
+# end
+defroute_with(routing_field_path_name)
+ routing_field_path=public_field_path(routing_field_path_name,explanation:"it is referenced as an index `route_with` field")
+
+ unlessrouting_field_path.type.leaf?
+ raiseErrors::SchemaError,"shard routing field `#{routing_field_path.full_description}` cannot be used for routing since it is not a leaf field."
+ end
+
+ self.routing_field_path=routing_field_path
+
+ routing_field_path.path_parts[0..-2].each{|f|f.json_schemanullable:false}
+ routing_field_path.last_part.json_schemanullable:false,pattern:HAS_NON_WHITE_SPACE_REGEX
+ indexed_type.append_to_documentation"For more performant queries on this type, please filter on `#{routing_field_path_name}` if possible."
+ end
+
+ # @see #route_with
+# @return [Boolean] whether or not this index uses custom shard routing
+defuses_custom_routing?
+ routing_field_path.path_in_index!="id"
+ end
+
+ # @return [Hash<String, Object>] datastore configuration for this index for when it does not use rollover
+defto_index_config
+ {
+ "aliases"=>{},
+ "mappings"=>mappings,
+ "settings"=>settings
+ }.compact
+ end
+
+ # @return [Hash<String, Object>] datastore configuration for the index template that will be defined if rollover is used
+defto_index_template_config
+ {
+ "index_patterns"=>["#{name}#{ROLLOVER_INDEX_INFIX_MARKER}*"],
+ "template"=>{
+ "aliases"=>{},
+ "mappings"=>mappings,
+ "settings"=>settings
+ }
+ }
+ end
+
+ # @return [SchemaArtifacts::RuntimeMetadata::IndexDefinition] runtime metadata for this index
+defruntime_metadata
+ SchemaArtifacts::RuntimeMetadata::IndexDefinition.new(
+ route_with:routing_field_path.path_in_index,
+ rollover:rollover_config&.runtime_metadata,
+ current_sources:indexed_type.current_sources,
+ fields_by_path:indexed_type.index_field_runtime_metadata_tuples.to_h,
+ default_sort_fields:default_sort_pairs.each_slice(2).mapdo|(graphql_field_path_name,direction)|
+ SchemaArtifacts::RuntimeMetadata::SortField.new(
+ field_path:public_field_path(graphql_field_path_name,explanation:"it is referenced as an index `default_sort` field").path_in_index,
+ direction:direction
+ )
+ end
+ )
+ end
+
+ private
+
+ # A regex that requires at least one non-whitespace character.
+# Note: this does not use the `/S` character class because it's recommended to use a small subset
+# of Regex syntax:
+#
+# > The regular expression syntax used is from JavaScript (ECMA 262, specifically). However, that
+# > complete syntax is not widely supported, therefore it is recommended that you stick to the subset
+# > of that syntax described below.
+#
+# (From https://json-schema.org/understanding-json-schema/reference/regular_expressions.html)
+HAS_NON_WHITE_SPACE_REGEX="[^ \t\n]+"
+
+ DEFAULT_SETTINGS={
+ "index.mapping.ignore_malformed"=>false,
+ "index.mapping.coerce"=>false,
+ "index.number_of_replicas"=>1,
+ "index.number_of_shards"=>1
+ }
+
+ defmappings
+ field_mappings=indexed_type
+ .to_indexing_field_type
+ .to_mapping
+ .except("type")# `type` is invalid at the mapping root because it always has to be an object.
+.then{|mapping|ListCountsMapping.merged_into(mapping,for_type:indexed_type)}
+ .thendo|fm|
+ Support::HashUtil.deep_merge(fm,{"properties"=>{
+ "__sources"=>{"type"=>"keyword"},
+ "__versions"=>{
+ "type"=>"object",
+ # __versions is map keyed by relationship name, with values that are maps keyed by id. Since it's not
+# a static object with known fields, we need to use dynamic here. Passing `false` allows some level
+# of dynamicness. As per https://www.elastic.co/guide/en/elasticsearch/reference/8.7/dynamic.html#dynamic-parameters:
+#
+# > New fields are ignored. These fields will not be indexed or searchable, but will still appear in the _source
+# > field of returned hits. These fields will not be added to the mapping, and new fields must be added explicitly.
+#
+# We need `__versions` to be in `_source` (so that our update scripts can operate on it), but
+# have no need for it to be searchable (as it's just an internal data structure used for indexing).
+#
+# Note: we intentionally set false as a string here, because that's how the datastore echoes it back
+# to us when you query the mapping (even if you set it as a boolean). Our checks for index mapping
+# consistency fail validation if we set it as a boolean since the datastore doesn't echo it back as
+# a boolean.
+"dynamic"=>"false"
+ }
+ }})
+ end
+
+ {"dynamic"=>"strict"}.merge(field_mappings).tapdo|hash|
+ # If we are using custom shard routing, we want to require a `routing` value to be provided
+# in every single index, get, delete or update request; otherwise the request might be
+# made against the wrong shard.
+hash["_routing"]={"required"=>true}ifuses_custom_routing?
+ hash["_size"]={"enabled"=>true}ifschema_def_state.index_document_sizes?
+ end
+ end
+
+ defpublic_field_path(public_path_string,explanation:)
+ parent_is_not_list=->(parent_field){!parent_field.type.list?}
+ resolver=SchemaElements::FieldPath::Resolver.new
+ resolved_path=resolver.resolve_public_path(indexed_type,public_path_string,&parent_is_not_list)
+ returnresolved_pathifresolved_path
+
+ path_parts=public_path_string.split(".")
+ error_msg="Field `#{indexed_type.name}.#{public_path_string}` cannot be resolved, but #{explanation}."
+
+ # If it is a nested field path, the problem could be that a type has been referenced which does not exist, so mention that.
+ifpath_parts.size>1
+ error_msg+=" Verify that all fields and types referenced by `#{public_path_string}` are defined."
+ end
+
+ # If the first part of the path doesn't resolve, the problem could be that the field is defined after the `index` call
+# but it needs to be defined before it, so mention that.
+ifresolver.resolve_public_path(indexed_type,path_parts.first,&parent_is_not_list).nil?
+ error_msg+=" Note: the `#{indexed_type.name}.#{path_parts.first}` definition must come before the `index` call."
+ end
+
+ raiseErrors::SchemaError,error_msg
+ end
+
+ defdate_and_datetime_types
+ @date_and_datetime_types||=%w[DateDateTime].mapdo|type|
+ schema_def_state.type_namer.name_for(type)
+ end
+ end
+end
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/indexing/index.rb', line 39
+
+classIndex<Struct.new(:name,:default_sort_pairs,:settings,:schema_def_state,:indexed_type,:routing_field_path,:rollover_config)
+ includeMixins::HasReadableToSAndInspect.new{|i|i.name}
+
+ # @param name [String] name of the index
+# @param settings [Hash<(String, Object)>] datastore settings for the index
+# @param schema_def_state [State] schema definition state
+# @param indexed_type [SchemaElements::ObjectType, SchemaElements::InterfaceType, SchemaElements::UnionType] type backed by this index
+# @yield [Index] the index, for further customization
+# @api private
+definitialize(name,settings,schema_def_state,indexed_type)
+ ifname.include?(ROLLOVER_INDEX_INFIX_MARKER)
+ raiseErrors::SchemaError,"`#{name}` is an invalid index definition name since it contains " \
+ "`#{ROLLOVER_INDEX_INFIX_MARKER}` which ElasticGraph treats as special."
+ end
+
+ settings=DEFAULT_SETTINGS.merge(Support::HashUtil.flatten_and_stringify_keys(settings,prefix:"index"))
+
+ super(name,[],settings,schema_def_state,indexed_type,[],nil)
+
+ # `id` is the field Elasticsearch/OpenSearch use for routing by default:
+# https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-routing-field.html
+# By using it here, it will cause queries to pass a `routing` parameter when
+# searching with id filtering on an index that does not use custom shard routing, giving
+# us a nice efficiency boost.
+self.routing_field_path=public_field_path("id",explanation:"indexed types must have an `id` field")
+
+ yieldselfifblock_given?
+ end
+
+ # Specifies how documents in this index should sort by default, when no `orderBy` argument is provided to the GraphQL query.
+#
+# @note the field name strings can be a dot-separated nested fields, but all referenced
+# fields must exist when this is called.
+#
+# @param field_name_direction_pairs [Array<(String, Symbol)>] pairs of field names and `:asc` or `:desc`
+# @return [void]
+#
+# @example Sort on `name` (ascending) with `createdAt` (descending) as a tie-breaker
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Campaign" do |t|
+# t.field "id", "ID!"
+# t.field "name", "String"
+# t.field "createdAt", "DateTime"
+#
+# t.index "campaigns"do |i|
+# i.default_sort "name", :asc, "createdAt", :desc
+# end
+# end
+# end
+defdefault_sort(*field_name_direction_pairs)
+ self.default_sort_pairs=field_name_direction_pairs
+ end
+
+ # Causes this index to "rollover" at the provided `frequency` based on the value of the provided `timestamp_field_path_name`.
+# This is particularly useful for time-series data. Partitioning the data into `hourly`, `daily`, `monthly` or `yearly` buckets
+# allows for different index configurations, and can be necessary when a dataset is too large to fit in one dataset given
+# Elasticsearch/OpenSearch limitations on the number of shards in one index. In addition, ElasticGraph optimizes queries which
+# filter on the timestamp field to target the subset of the indices in which matching documents could reside.
+#
+# @note the timestamp field specified here **must be immutable**. To understand why, consider a `:yearly` rollover
+# index used for data based on `createdAt`; if ElasticGraph ingests record `123` with a createdAt of `2023-12-31T23:59:59Z`, it
+# will be indexed in the `2023` index. Later if it receives an update event for record `123` with a `createdAt` of
+# `2024-01-01T00:00:00Z` (a mere one second later!), ElasticGraph will store the new version of the payment in the `2024` index,
+# and leave the old copy of the payment in the `2023` index unchanged. It’ll have duplicates for that document.
+# @note changing the `rollover` configuration on an existing index that already has data will result in duplicate documents
+#
+# @param frequency [:yearly, :monthly, :daily, :hourly] how often to rollover the index
+# @param timestamp_field_path_name [String] dot-separated path to the timestamp field used for rollover. Note: all referenced
+# fields must exist when this is called.
+# @return [void]
+#
+# @example Define a `campaigns` index to rollover yearly based on `createdAt`
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Campaign" do |t|
+# t.field "id", "ID!"
+# t.field "name", "String"
+# t.field "createdAt", "DateTime"
+#
+# t.index "campaigns"do |i|
+# i.rollover :yearly, "createdAt"
+# end
+# end
+# end
+defrollover(frequency,timestamp_field_path_name)
+ timestamp_field_path=public_field_path(timestamp_field_path_name,explanation:"it is referenced as an index `rollover` field")
+
+ unlessdate_and_datetime_types.include?(timestamp_field_path.type.fully_unwrapped.name)
+ date_or_datetime_description=date_and_datetime_types.map{|t|"`#{t}`"}.join(" or ")
+ raiseErrors::SchemaError,"rollover field `#{timestamp_field_path.full_description}` cannot be used for rollover since it is not a #{date_or_datetime_description} field."
+ end
+
+ iftimestamp_field_path.type.list?
+ raiseErrors::SchemaError,"rollover field `#{timestamp_field_path.full_description}` cannot be used for rollover since it is a list field."
+ end
+
+ timestamp_field_path.path_parts.each{|f|f.json_schemanullable:false}
+
+ self.rollover_config=RolloverConfig.new(
+ frequency:frequency,
+ timestamp_field_path:timestamp_field_path
+ )
+ end
+
+ # Configures the index to [route documents to shards](https://www.elastic.co/guide/en/elasticsearch/reference/8.15/mapping-routing-field.html)
+# based on the specified field. ElasticGraph optimizes queries that filter on the shard routing field so that they only run on a
+# subset of nodes instead of all nodes. This can make a big difference in query performance if queries usually filter on a certain
+# field. Using an appropriate field for shard routing is often essential for horizontal scaling, as it avoids having every query
+# hit every node, allowing additional nodes to increase query throughput.
+#
+# @note it is essential that the shards are well-balanced. If the data’s distribution is lopsided, using this feature can make
+# performance worse.
+# @note the routing field specified here **must be immutable**. If ElasticGraph receives an updated version of a document with a
+# different routing value, it’ll write the new version of the document to a different shard and leave the copy on the old shard
+# unchanged, leading to duplicates.
+# @note changing the shard routing configuration on an existing index that already has data will result in duplicate documents
+#
+# @param routing_field_path_name [String] dot-separated path to the field used for shard routing. Note: all referenced
+# fields must exist when this is called.
+# @return [void]
+#
+# @example Define a `campaigns` index to shard on `organizationId`
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Campaign" do |t|
+# t.field "id", "ID!"
+# t.field "name", "String"
+# t.field "organizationId", "ID"
+#
+# t.index "campaigns"do |i|
+# i.route_with "organizationId"
+# end
+# end
+# end
+defroute_with(routing_field_path_name)
+ routing_field_path=public_field_path(routing_field_path_name,explanation:"it is referenced as an index `route_with` field")
+
+ unlessrouting_field_path.type.leaf?
+ raiseErrors::SchemaError,"shard routing field `#{routing_field_path.full_description}` cannot be used for routing since it is not a leaf field."
+ end
+
+ self.routing_field_path=routing_field_path
+
+ routing_field_path.path_parts[0..-2].each{|f|f.json_schemanullable:false}
+ routing_field_path.last_part.json_schemanullable:false,pattern:HAS_NON_WHITE_SPACE_REGEX
+ indexed_type.append_to_documentation"For more performant queries on this type, please filter on `#{routing_field_path_name}` if possible."
+ end
+
+ # @see #route_with
+# @return [Boolean] whether or not this index uses custom shard routing
+defuses_custom_routing?
+ routing_field_path.path_in_index!="id"
+ end
+
+ # @return [Hash<String, Object>] datastore configuration for this index for when it does not use rollover
+defto_index_config
+ {
+ "aliases"=>{},
+ "mappings"=>mappings,
+ "settings"=>settings
+ }.compact
+ end
+
+ # @return [Hash<String, Object>] datastore configuration for the index template that will be defined if rollover is used
+defto_index_template_config
+ {
+ "index_patterns"=>["#{name}#{ROLLOVER_INDEX_INFIX_MARKER}*"],
+ "template"=>{
+ "aliases"=>{},
+ "mappings"=>mappings,
+ "settings"=>settings
+ }
+ }
+ end
+
+ # @return [SchemaArtifacts::RuntimeMetadata::IndexDefinition] runtime metadata for this index
+defruntime_metadata
+ SchemaArtifacts::RuntimeMetadata::IndexDefinition.new(
+ route_with:routing_field_path.path_in_index,
+ rollover:rollover_config&.runtime_metadata,
+ current_sources:indexed_type.current_sources,
+ fields_by_path:indexed_type.index_field_runtime_metadata_tuples.to_h,
+ default_sort_fields:default_sort_pairs.each_slice(2).mapdo|(graphql_field_path_name,direction)|
+ SchemaArtifacts::RuntimeMetadata::SortField.new(
+ field_path:public_field_path(graphql_field_path_name,explanation:"it is referenced as an index `default_sort` field").path_in_index,
+ direction:direction
+ )
+ end
+ )
+ end
+
+ private
+
+ # A regex that requires at least one non-whitespace character.
+# Note: this does not use the `/S` character class because it's recommended to use a small subset
+# of Regex syntax:
+#
+# > The regular expression syntax used is from JavaScript (ECMA 262, specifically). However, that
+# > complete syntax is not widely supported, therefore it is recommended that you stick to the subset
+# > of that syntax described below.
+#
+# (From https://json-schema.org/understanding-json-schema/reference/regular_expressions.html)
+HAS_NON_WHITE_SPACE_REGEX="[^ \t\n]+"
+
+ DEFAULT_SETTINGS={
+ "index.mapping.ignore_malformed"=>false,
+ "index.mapping.coerce"=>false,
+ "index.number_of_replicas"=>1,
+ "index.number_of_shards"=>1
+ }
+
+ defmappings
+ field_mappings=indexed_type
+ .to_indexing_field_type
+ .to_mapping
+ .except("type")# `type` is invalid at the mapping root because it always has to be an object.
+.then{|mapping|ListCountsMapping.merged_into(mapping,for_type:indexed_type)}
+ .thendo|fm|
+ Support::HashUtil.deep_merge(fm,{"properties"=>{
+ "__sources"=>{"type"=>"keyword"},
+ "__versions"=>{
+ "type"=>"object",
+ # __versions is map keyed by relationship name, with values that are maps keyed by id. Since it's not
+# a static object with known fields, we need to use dynamic here. Passing `false` allows some level
+# of dynamicness. As per https://www.elastic.co/guide/en/elasticsearch/reference/8.7/dynamic.html#dynamic-parameters:
+#
+# > New fields are ignored. These fields will not be indexed or searchable, but will still appear in the _source
+# > field of returned hits. These fields will not be added to the mapping, and new fields must be added explicitly.
+#
+# We need `__versions` to be in `_source` (so that our update scripts can operate on it), but
+# have no need for it to be searchable (as it's just an internal data structure used for indexing).
+#
+# Note: we intentionally set false as a string here, because that's how the datastore echoes it back
+# to us when you query the mapping (even if you set it as a boolean). Our checks for index mapping
+# consistency fail validation if we set it as a boolean since the datastore doesn't echo it back as
+# a boolean.
+"dynamic"=>"false"
+ }
+ }})
+ end
+
+ {"dynamic"=>"strict"}.merge(field_mappings).tapdo|hash|
+ # If we are using custom shard routing, we want to require a `routing` value to be provided
+# in every single index, get, delete or update request; otherwise the request might be
+# made against the wrong shard.
+hash["_routing"]={"required"=>true}ifuses_custom_routing?
+ hash["_size"]={"enabled"=>true}ifschema_def_state.index_document_sizes?
+ end
+ end
+
+ defpublic_field_path(public_path_string,explanation:)
+ parent_is_not_list=->(parent_field){!parent_field.type.list?}
+ resolver=SchemaElements::FieldPath::Resolver.new
+ resolved_path=resolver.resolve_public_path(indexed_type,public_path_string,&parent_is_not_list)
+ returnresolved_pathifresolved_path
+
+ path_parts=public_path_string.split(".")
+ error_msg="Field `#{indexed_type.name}.#{public_path_string}` cannot be resolved, but #{explanation}."
+
+ # If it is a nested field path, the problem could be that a type has been referenced which does not exist, so mention that.
+ifpath_parts.size>1
+ error_msg+=" Verify that all fields and types referenced by `#{public_path_string}` are defined."
+ end
+
+ # If the first part of the path doesn't resolve, the problem could be that the field is defined after the `index` call
+# but it needs to be defined before it, so mention that.
+ifresolver.resolve_public_path(indexed_type,path_parts.first,&parent_is_not_list).nil?
+ error_msg+=" Note: the `#{indexed_type.name}.#{path_parts.first}` definition must come before the `index` call."
+ end
+
+ raiseErrors::SchemaError,error_msg
+ end
+
+ defdate_and_datetime_types
+ @date_and_datetime_types||=%w[DateDateTime].mapdo|type|
+ schema_def_state.type_namer.name_for(type)
+ end
+ end
+end
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/indexing/index.rb', line 39
+
+classIndex<Struct.new(:name,:default_sort_pairs,:settings,:schema_def_state,:indexed_type,:routing_field_path,:rollover_config)
+ includeMixins::HasReadableToSAndInspect.new{|i|i.name}
+
+ # @param name [String] name of the index
+# @param settings [Hash<(String, Object)>] datastore settings for the index
+# @param schema_def_state [State] schema definition state
+# @param indexed_type [SchemaElements::ObjectType, SchemaElements::InterfaceType, SchemaElements::UnionType] type backed by this index
+# @yield [Index] the index, for further customization
+# @api private
+definitialize(name,settings,schema_def_state,indexed_type)
+ ifname.include?(ROLLOVER_INDEX_INFIX_MARKER)
+ raiseErrors::SchemaError,"`#{name}` is an invalid index definition name since it contains " \
+ "`#{ROLLOVER_INDEX_INFIX_MARKER}` which ElasticGraph treats as special."
+ end
+
+ settings=DEFAULT_SETTINGS.merge(Support::HashUtil.flatten_and_stringify_keys(settings,prefix:"index"))
+
+ super(name,[],settings,schema_def_state,indexed_type,[],nil)
+
+ # `id` is the field Elasticsearch/OpenSearch use for routing by default:
+# https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-routing-field.html
+# By using it here, it will cause queries to pass a `routing` parameter when
+# searching with id filtering on an index that does not use custom shard routing, giving
+# us a nice efficiency boost.
+self.routing_field_path=public_field_path("id",explanation:"indexed types must have an `id` field")
+
+ yieldselfifblock_given?
+ end
+
+ # Specifies how documents in this index should sort by default, when no `orderBy` argument is provided to the GraphQL query.
+#
+# @note the field name strings can be a dot-separated nested fields, but all referenced
+# fields must exist when this is called.
+#
+# @param field_name_direction_pairs [Array<(String, Symbol)>] pairs of field names and `:asc` or `:desc`
+# @return [void]
+#
+# @example Sort on `name` (ascending) with `createdAt` (descending) as a tie-breaker
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Campaign" do |t|
+# t.field "id", "ID!"
+# t.field "name", "String"
+# t.field "createdAt", "DateTime"
+#
+# t.index "campaigns"do |i|
+# i.default_sort "name", :asc, "createdAt", :desc
+# end
+# end
+# end
+defdefault_sort(*field_name_direction_pairs)
+ self.default_sort_pairs=field_name_direction_pairs
+ end
+
+ # Causes this index to "rollover" at the provided `frequency` based on the value of the provided `timestamp_field_path_name`.
+# This is particularly useful for time-series data. Partitioning the data into `hourly`, `daily`, `monthly` or `yearly` buckets
+# allows for different index configurations, and can be necessary when a dataset is too large to fit in one dataset given
+# Elasticsearch/OpenSearch limitations on the number of shards in one index. In addition, ElasticGraph optimizes queries which
+# filter on the timestamp field to target the subset of the indices in which matching documents could reside.
+#
+# @note the timestamp field specified here **must be immutable**. To understand why, consider a `:yearly` rollover
+# index used for data based on `createdAt`; if ElasticGraph ingests record `123` with a createdAt of `2023-12-31T23:59:59Z`, it
+# will be indexed in the `2023` index. Later if it receives an update event for record `123` with a `createdAt` of
+# `2024-01-01T00:00:00Z` (a mere one second later!), ElasticGraph will store the new version of the payment in the `2024` index,
+# and leave the old copy of the payment in the `2023` index unchanged. It’ll have duplicates for that document.
+# @note changing the `rollover` configuration on an existing index that already has data will result in duplicate documents
+#
+# @param frequency [:yearly, :monthly, :daily, :hourly] how often to rollover the index
+# @param timestamp_field_path_name [String] dot-separated path to the timestamp field used for rollover. Note: all referenced
+# fields must exist when this is called.
+# @return [void]
+#
+# @example Define a `campaigns` index to rollover yearly based on `createdAt`
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Campaign" do |t|
+# t.field "id", "ID!"
+# t.field "name", "String"
+# t.field "createdAt", "DateTime"
+#
+# t.index "campaigns"do |i|
+# i.rollover :yearly, "createdAt"
+# end
+# end
+# end
+defrollover(frequency,timestamp_field_path_name)
+ timestamp_field_path=public_field_path(timestamp_field_path_name,explanation:"it is referenced as an index `rollover` field")
+
+ unlessdate_and_datetime_types.include?(timestamp_field_path.type.fully_unwrapped.name)
+ date_or_datetime_description=date_and_datetime_types.map{|t|"`#{t}`"}.join(" or ")
+ raiseErrors::SchemaError,"rollover field `#{timestamp_field_path.full_description}` cannot be used for rollover since it is not a #{date_or_datetime_description} field."
+ end
+
+ iftimestamp_field_path.type.list?
+ raiseErrors::SchemaError,"rollover field `#{timestamp_field_path.full_description}` cannot be used for rollover since it is a list field."
+ end
+
+ timestamp_field_path.path_parts.each{|f|f.json_schemanullable:false}
+
+ self.rollover_config=RolloverConfig.new(
+ frequency:frequency,
+ timestamp_field_path:timestamp_field_path
+ )
+ end
+
+ # Configures the index to [route documents to shards](https://www.elastic.co/guide/en/elasticsearch/reference/8.15/mapping-routing-field.html)
+# based on the specified field. ElasticGraph optimizes queries that filter on the shard routing field so that they only run on a
+# subset of nodes instead of all nodes. This can make a big difference in query performance if queries usually filter on a certain
+# field. Using an appropriate field for shard routing is often essential for horizontal scaling, as it avoids having every query
+# hit every node, allowing additional nodes to increase query throughput.
+#
+# @note it is essential that the shards are well-balanced. If the data’s distribution is lopsided, using this feature can make
+# performance worse.
+# @note the routing field specified here **must be immutable**. If ElasticGraph receives an updated version of a document with a
+# different routing value, it’ll write the new version of the document to a different shard and leave the copy on the old shard
+# unchanged, leading to duplicates.
+# @note changing the shard routing configuration on an existing index that already has data will result in duplicate documents
+#
+# @param routing_field_path_name [String] dot-separated path to the field used for shard routing. Note: all referenced
+# fields must exist when this is called.
+# @return [void]
+#
+# @example Define a `campaigns` index to shard on `organizationId`
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Campaign" do |t|
+# t.field "id", "ID!"
+# t.field "name", "String"
+# t.field "organizationId", "ID"
+#
+# t.index "campaigns"do |i|
+# i.route_with "organizationId"
+# end
+# end
+# end
+defroute_with(routing_field_path_name)
+ routing_field_path=public_field_path(routing_field_path_name,explanation:"it is referenced as an index `route_with` field")
+
+ unlessrouting_field_path.type.leaf?
+ raiseErrors::SchemaError,"shard routing field `#{routing_field_path.full_description}` cannot be used for routing since it is not a leaf field."
+ end
+
+ self.routing_field_path=routing_field_path
+
+ routing_field_path.path_parts[0..-2].each{|f|f.json_schemanullable:false}
+ routing_field_path.last_part.json_schemanullable:false,pattern:HAS_NON_WHITE_SPACE_REGEX
+ indexed_type.append_to_documentation"For more performant queries on this type, please filter on `#{routing_field_path_name}` if possible."
+ end
+
+ # @see #route_with
+# @return [Boolean] whether or not this index uses custom shard routing
+defuses_custom_routing?
+ routing_field_path.path_in_index!="id"
+ end
+
+ # @return [Hash<String, Object>] datastore configuration for this index for when it does not use rollover
+defto_index_config
+ {
+ "aliases"=>{},
+ "mappings"=>mappings,
+ "settings"=>settings
+ }.compact
+ end
+
+ # @return [Hash<String, Object>] datastore configuration for the index template that will be defined if rollover is used
+defto_index_template_config
+ {
+ "index_patterns"=>["#{name}#{ROLLOVER_INDEX_INFIX_MARKER}*"],
+ "template"=>{
+ "aliases"=>{},
+ "mappings"=>mappings,
+ "settings"=>settings
+ }
+ }
+ end
+
+ # @return [SchemaArtifacts::RuntimeMetadata::IndexDefinition] runtime metadata for this index
+defruntime_metadata
+ SchemaArtifacts::RuntimeMetadata::IndexDefinition.new(
+ route_with:routing_field_path.path_in_index,
+ rollover:rollover_config&.runtime_metadata,
+ current_sources:indexed_type.current_sources,
+ fields_by_path:indexed_type.index_field_runtime_metadata_tuples.to_h,
+ default_sort_fields:default_sort_pairs.each_slice(2).mapdo|(graphql_field_path_name,direction)|
+ SchemaArtifacts::RuntimeMetadata::SortField.new(
+ field_path:public_field_path(graphql_field_path_name,explanation:"it is referenced as an index `default_sort` field").path_in_index,
+ direction:direction
+ )
+ end
+ )
+ end
+
+ private
+
+ # A regex that requires at least one non-whitespace character.
+# Note: this does not use the `/S` character class because it's recommended to use a small subset
+# of Regex syntax:
+#
+# > The regular expression syntax used is from JavaScript (ECMA 262, specifically). However, that
+# > complete syntax is not widely supported, therefore it is recommended that you stick to the subset
+# > of that syntax described below.
+#
+# (From https://json-schema.org/understanding-json-schema/reference/regular_expressions.html)
+HAS_NON_WHITE_SPACE_REGEX="[^ \t\n]+"
+
+ DEFAULT_SETTINGS={
+ "index.mapping.ignore_malformed"=>false,
+ "index.mapping.coerce"=>false,
+ "index.number_of_replicas"=>1,
+ "index.number_of_shards"=>1
+ }
+
+ defmappings
+ field_mappings=indexed_type
+ .to_indexing_field_type
+ .to_mapping
+ .except("type")# `type` is invalid at the mapping root because it always has to be an object.
+.then{|mapping|ListCountsMapping.merged_into(mapping,for_type:indexed_type)}
+ .thendo|fm|
+ Support::HashUtil.deep_merge(fm,{"properties"=>{
+ "__sources"=>{"type"=>"keyword"},
+ "__versions"=>{
+ "type"=>"object",
+ # __versions is map keyed by relationship name, with values that are maps keyed by id. Since it's not
+# a static object with known fields, we need to use dynamic here. Passing `false` allows some level
+# of dynamicness. As per https://www.elastic.co/guide/en/elasticsearch/reference/8.7/dynamic.html#dynamic-parameters:
+#
+# > New fields are ignored. These fields will not be indexed or searchable, but will still appear in the _source
+# > field of returned hits. These fields will not be added to the mapping, and new fields must be added explicitly.
+#
+# We need `__versions` to be in `_source` (so that our update scripts can operate on it), but
+# have no need for it to be searchable (as it's just an internal data structure used for indexing).
+#
+# Note: we intentionally set false as a string here, because that's how the datastore echoes it back
+# to us when you query the mapping (even if you set it as a boolean). Our checks for index mapping
+# consistency fail validation if we set it as a boolean since the datastore doesn't echo it back as
+# a boolean.
+"dynamic"=>"false"
+ }
+ }})
+ end
+
+ {"dynamic"=>"strict"}.merge(field_mappings).tapdo|hash|
+ # If we are using custom shard routing, we want to require a `routing` value to be provided
+# in every single index, get, delete or update request; otherwise the request might be
+# made against the wrong shard.
+hash["_routing"]={"required"=>true}ifuses_custom_routing?
+ hash["_size"]={"enabled"=>true}ifschema_def_state.index_document_sizes?
+ end
+ end
+
+ defpublic_field_path(public_path_string,explanation:)
+ parent_is_not_list=->(parent_field){!parent_field.type.list?}
+ resolver=SchemaElements::FieldPath::Resolver.new
+ resolved_path=resolver.resolve_public_path(indexed_type,public_path_string,&parent_is_not_list)
+ returnresolved_pathifresolved_path
+
+ path_parts=public_path_string.split(".")
+ error_msg="Field `#{indexed_type.name}.#{public_path_string}` cannot be resolved, but #{explanation}."
+
+ # If it is a nested field path, the problem could be that a type has been referenced which does not exist, so mention that.
+ifpath_parts.size>1
+ error_msg+=" Verify that all fields and types referenced by `#{public_path_string}` are defined."
+ end
+
+ # If the first part of the path doesn't resolve, the problem could be that the field is defined after the `index` call
+# but it needs to be defined before it, so mention that.
+ifresolver.resolve_public_path(indexed_type,path_parts.first,&parent_is_not_list).nil?
+ error_msg+=" Note: the `#{indexed_type.name}.#{path_parts.first}` definition must come before the `index` call."
+ end
+
+ raiseErrors::SchemaError,error_msg
+ end
+
+ defdate_and_datetime_types
+ @date_and_datetime_types||=%w[DateDateTime].mapdo|type|
+ schema_def_state.type_namer.name_for(type)
+ end
+ end
+end
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/indexing/index.rb', line 39
+
+classIndex<Struct.new(:name,:default_sort_pairs,:settings,:schema_def_state,:indexed_type,:routing_field_path,:rollover_config)
+ includeMixins::HasReadableToSAndInspect.new{|i|i.name}
+
+ # @param name [String] name of the index
+# @param settings [Hash<(String, Object)>] datastore settings for the index
+# @param schema_def_state [State] schema definition state
+# @param indexed_type [SchemaElements::ObjectType, SchemaElements::InterfaceType, SchemaElements::UnionType] type backed by this index
+# @yield [Index] the index, for further customization
+# @api private
+definitialize(name,settings,schema_def_state,indexed_type)
+ ifname.include?(ROLLOVER_INDEX_INFIX_MARKER)
+ raiseErrors::SchemaError,"`#{name}` is an invalid index definition name since it contains " \
+ "`#{ROLLOVER_INDEX_INFIX_MARKER}` which ElasticGraph treats as special."
+ end
+
+ settings=DEFAULT_SETTINGS.merge(Support::HashUtil.flatten_and_stringify_keys(settings,prefix:"index"))
+
+ super(name,[],settings,schema_def_state,indexed_type,[],nil)
+
+ # `id` is the field Elasticsearch/OpenSearch use for routing by default:
+# https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-routing-field.html
+# By using it here, it will cause queries to pass a `routing` parameter when
+# searching with id filtering on an index that does not use custom shard routing, giving
+# us a nice efficiency boost.
+self.routing_field_path=public_field_path("id",explanation:"indexed types must have an `id` field")
+
+ yieldselfifblock_given?
+ end
+
+ # Specifies how documents in this index should sort by default, when no `orderBy` argument is provided to the GraphQL query.
+#
+# @note the field name strings can be a dot-separated nested fields, but all referenced
+# fields must exist when this is called.
+#
+# @param field_name_direction_pairs [Array<(String, Symbol)>] pairs of field names and `:asc` or `:desc`
+# @return [void]
+#
+# @example Sort on `name` (ascending) with `createdAt` (descending) as a tie-breaker
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Campaign" do |t|
+# t.field "id", "ID!"
+# t.field "name", "String"
+# t.field "createdAt", "DateTime"
+#
+# t.index "campaigns"do |i|
+# i.default_sort "name", :asc, "createdAt", :desc
+# end
+# end
+# end
+defdefault_sort(*field_name_direction_pairs)
+ self.default_sort_pairs=field_name_direction_pairs
+ end
+
+ # Causes this index to "rollover" at the provided `frequency` based on the value of the provided `timestamp_field_path_name`.
+# This is particularly useful for time-series data. Partitioning the data into `hourly`, `daily`, `monthly` or `yearly` buckets
+# allows for different index configurations, and can be necessary when a dataset is too large to fit in one dataset given
+# Elasticsearch/OpenSearch limitations on the number of shards in one index. In addition, ElasticGraph optimizes queries which
+# filter on the timestamp field to target the subset of the indices in which matching documents could reside.
+#
+# @note the timestamp field specified here **must be immutable**. To understand why, consider a `:yearly` rollover
+# index used for data based on `createdAt`; if ElasticGraph ingests record `123` with a createdAt of `2023-12-31T23:59:59Z`, it
+# will be indexed in the `2023` index. Later if it receives an update event for record `123` with a `createdAt` of
+# `2024-01-01T00:00:00Z` (a mere one second later!), ElasticGraph will store the new version of the payment in the `2024` index,
+# and leave the old copy of the payment in the `2023` index unchanged. It’ll have duplicates for that document.
+# @note changing the `rollover` configuration on an existing index that already has data will result in duplicate documents
+#
+# @param frequency [:yearly, :monthly, :daily, :hourly] how often to rollover the index
+# @param timestamp_field_path_name [String] dot-separated path to the timestamp field used for rollover. Note: all referenced
+# fields must exist when this is called.
+# @return [void]
+#
+# @example Define a `campaigns` index to rollover yearly based on `createdAt`
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Campaign" do |t|
+# t.field "id", "ID!"
+# t.field "name", "String"
+# t.field "createdAt", "DateTime"
+#
+# t.index "campaigns"do |i|
+# i.rollover :yearly, "createdAt"
+# end
+# end
+# end
+defrollover(frequency,timestamp_field_path_name)
+ timestamp_field_path=public_field_path(timestamp_field_path_name,explanation:"it is referenced as an index `rollover` field")
+
+ unlessdate_and_datetime_types.include?(timestamp_field_path.type.fully_unwrapped.name)
+ date_or_datetime_description=date_and_datetime_types.map{|t|"`#{t}`"}.join(" or ")
+ raiseErrors::SchemaError,"rollover field `#{timestamp_field_path.full_description}` cannot be used for rollover since it is not a #{date_or_datetime_description} field."
+ end
+
+ iftimestamp_field_path.type.list?
+ raiseErrors::SchemaError,"rollover field `#{timestamp_field_path.full_description}` cannot be used for rollover since it is a list field."
+ end
+
+ timestamp_field_path.path_parts.each{|f|f.json_schemanullable:false}
+
+ self.rollover_config=RolloverConfig.new(
+ frequency:frequency,
+ timestamp_field_path:timestamp_field_path
+ )
+ end
+
+ # Configures the index to [route documents to shards](https://www.elastic.co/guide/en/elasticsearch/reference/8.15/mapping-routing-field.html)
+# based on the specified field. ElasticGraph optimizes queries that filter on the shard routing field so that they only run on a
+# subset of nodes instead of all nodes. This can make a big difference in query performance if queries usually filter on a certain
+# field. Using an appropriate field for shard routing is often essential for horizontal scaling, as it avoids having every query
+# hit every node, allowing additional nodes to increase query throughput.
+#
+# @note it is essential that the shards are well-balanced. If the data’s distribution is lopsided, using this feature can make
+# performance worse.
+# @note the routing field specified here **must be immutable**. If ElasticGraph receives an updated version of a document with a
+# different routing value, it’ll write the new version of the document to a different shard and leave the copy on the old shard
+# unchanged, leading to duplicates.
+# @note changing the shard routing configuration on an existing index that already has data will result in duplicate documents
+#
+# @param routing_field_path_name [String] dot-separated path to the field used for shard routing. Note: all referenced
+# fields must exist when this is called.
+# @return [void]
+#
+# @example Define a `campaigns` index to shard on `organizationId`
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Campaign" do |t|
+# t.field "id", "ID!"
+# t.field "name", "String"
+# t.field "organizationId", "ID"
+#
+# t.index "campaigns"do |i|
+# i.route_with "organizationId"
+# end
+# end
+# end
+defroute_with(routing_field_path_name)
+ routing_field_path=public_field_path(routing_field_path_name,explanation:"it is referenced as an index `route_with` field")
+
+ unlessrouting_field_path.type.leaf?
+ raiseErrors::SchemaError,"shard routing field `#{routing_field_path.full_description}` cannot be used for routing since it is not a leaf field."
+ end
+
+ self.routing_field_path=routing_field_path
+
+ routing_field_path.path_parts[0..-2].each{|f|f.json_schemanullable:false}
+ routing_field_path.last_part.json_schemanullable:false,pattern:HAS_NON_WHITE_SPACE_REGEX
+ indexed_type.append_to_documentation"For more performant queries on this type, please filter on `#{routing_field_path_name}` if possible."
+ end
+
+ # @see #route_with
+# @return [Boolean] whether or not this index uses custom shard routing
+defuses_custom_routing?
+ routing_field_path.path_in_index!="id"
+ end
+
+ # @return [Hash<String, Object>] datastore configuration for this index for when it does not use rollover
+defto_index_config
+ {
+ "aliases"=>{},
+ "mappings"=>mappings,
+ "settings"=>settings
+ }.compact
+ end
+
+ # @return [Hash<String, Object>] datastore configuration for the index template that will be defined if rollover is used
+defto_index_template_config
+ {
+ "index_patterns"=>["#{name}#{ROLLOVER_INDEX_INFIX_MARKER}*"],
+ "template"=>{
+ "aliases"=>{},
+ "mappings"=>mappings,
+ "settings"=>settings
+ }
+ }
+ end
+
+ # @return [SchemaArtifacts::RuntimeMetadata::IndexDefinition] runtime metadata for this index
+defruntime_metadata
+ SchemaArtifacts::RuntimeMetadata::IndexDefinition.new(
+ route_with:routing_field_path.path_in_index,
+ rollover:rollover_config&.runtime_metadata,
+ current_sources:indexed_type.current_sources,
+ fields_by_path:indexed_type.index_field_runtime_metadata_tuples.to_h,
+ default_sort_fields:default_sort_pairs.each_slice(2).mapdo|(graphql_field_path_name,direction)|
+ SchemaArtifacts::RuntimeMetadata::SortField.new(
+ field_path:public_field_path(graphql_field_path_name,explanation:"it is referenced as an index `default_sort` field").path_in_index,
+ direction:direction
+ )
+ end
+ )
+ end
+
+ private
+
+ # A regex that requires at least one non-whitespace character.
+# Note: this does not use the `/S` character class because it's recommended to use a small subset
+# of Regex syntax:
+#
+# > The regular expression syntax used is from JavaScript (ECMA 262, specifically). However, that
+# > complete syntax is not widely supported, therefore it is recommended that you stick to the subset
+# > of that syntax described below.
+#
+# (From https://json-schema.org/understanding-json-schema/reference/regular_expressions.html)
+HAS_NON_WHITE_SPACE_REGEX="[^ \t\n]+"
+
+ DEFAULT_SETTINGS={
+ "index.mapping.ignore_malformed"=>false,
+ "index.mapping.coerce"=>false,
+ "index.number_of_replicas"=>1,
+ "index.number_of_shards"=>1
+ }
+
+ defmappings
+ field_mappings=indexed_type
+ .to_indexing_field_type
+ .to_mapping
+ .except("type")# `type` is invalid at the mapping root because it always has to be an object.
+.then{|mapping|ListCountsMapping.merged_into(mapping,for_type:indexed_type)}
+ .thendo|fm|
+ Support::HashUtil.deep_merge(fm,{"properties"=>{
+ "__sources"=>{"type"=>"keyword"},
+ "__versions"=>{
+ "type"=>"object",
+ # __versions is map keyed by relationship name, with values that are maps keyed by id. Since it's not
+# a static object with known fields, we need to use dynamic here. Passing `false` allows some level
+# of dynamicness. As per https://www.elastic.co/guide/en/elasticsearch/reference/8.7/dynamic.html#dynamic-parameters:
+#
+# > New fields are ignored. These fields will not be indexed or searchable, but will still appear in the _source
+# > field of returned hits. These fields will not be added to the mapping, and new fields must be added explicitly.
+#
+# We need `__versions` to be in `_source` (so that our update scripts can operate on it), but
+# have no need for it to be searchable (as it's just an internal data structure used for indexing).
+#
+# Note: we intentionally set false as a string here, because that's how the datastore echoes it back
+# to us when you query the mapping (even if you set it as a boolean). Our checks for index mapping
+# consistency fail validation if we set it as a boolean since the datastore doesn't echo it back as
+# a boolean.
+"dynamic"=>"false"
+ }
+ }})
+ end
+
+ {"dynamic"=>"strict"}.merge(field_mappings).tapdo|hash|
+ # If we are using custom shard routing, we want to require a `routing` value to be provided
+# in every single index, get, delete or update request; otherwise the request might be
+# made against the wrong shard.
+hash["_routing"]={"required"=>true}ifuses_custom_routing?
+ hash["_size"]={"enabled"=>true}ifschema_def_state.index_document_sizes?
+ end
+ end
+
+ defpublic_field_path(public_path_string,explanation:)
+ parent_is_not_list=->(parent_field){!parent_field.type.list?}
+ resolver=SchemaElements::FieldPath::Resolver.new
+ resolved_path=resolver.resolve_public_path(indexed_type,public_path_string,&parent_is_not_list)
+ returnresolved_pathifresolved_path
+
+ path_parts=public_path_string.split(".")
+ error_msg="Field `#{indexed_type.name}.#{public_path_string}` cannot be resolved, but #{explanation}."
+
+ # If it is a nested field path, the problem could be that a type has been referenced which does not exist, so mention that.
+ifpath_parts.size>1
+ error_msg+=" Verify that all fields and types referenced by `#{public_path_string}` are defined."
+ end
+
+ # If the first part of the path doesn't resolve, the problem could be that the field is defined after the `index` call
+# but it needs to be defined before it, so mention that.
+ifresolver.resolve_public_path(indexed_type,path_parts.first,&parent_is_not_list).nil?
+ error_msg+=" Note: the `#{indexed_type.name}.#{path_parts.first}` definition must come before the `index` call."
+ end
+
+ raiseErrors::SchemaError,error_msg
+ end
+
+ defdate_and_datetime_types
+ @date_and_datetime_types||=%w[DateDateTime].mapdo|type|
+ schema_def_state.type_namer.name_for(type)
+ end
+ end
+end
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/indexing/index.rb', line 39
+
+classIndex<Struct.new(:name,:default_sort_pairs,:settings,:schema_def_state,:indexed_type,:routing_field_path,:rollover_config)
+ includeMixins::HasReadableToSAndInspect.new{|i|i.name}
+
+ # @param name [String] name of the index
+# @param settings [Hash<(String, Object)>] datastore settings for the index
+# @param schema_def_state [State] schema definition state
+# @param indexed_type [SchemaElements::ObjectType, SchemaElements::InterfaceType, SchemaElements::UnionType] type backed by this index
+# @yield [Index] the index, for further customization
+# @api private
+definitialize(name,settings,schema_def_state,indexed_type)
+ ifname.include?(ROLLOVER_INDEX_INFIX_MARKER)
+ raiseErrors::SchemaError,"`#{name}` is an invalid index definition name since it contains " \
+ "`#{ROLLOVER_INDEX_INFIX_MARKER}` which ElasticGraph treats as special."
+ end
+
+ settings=DEFAULT_SETTINGS.merge(Support::HashUtil.flatten_and_stringify_keys(settings,prefix:"index"))
+
+ super(name,[],settings,schema_def_state,indexed_type,[],nil)
+
+ # `id` is the field Elasticsearch/OpenSearch use for routing by default:
+# https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-routing-field.html
+# By using it here, it will cause queries to pass a `routing` parameter when
+# searching with id filtering on an index that does not use custom shard routing, giving
+# us a nice efficiency boost.
+self.routing_field_path=public_field_path("id",explanation:"indexed types must have an `id` field")
+
+ yieldselfifblock_given?
+ end
+
+ # Specifies how documents in this index should sort by default, when no `orderBy` argument is provided to the GraphQL query.
+#
+# @note the field name strings can be a dot-separated nested fields, but all referenced
+# fields must exist when this is called.
+#
+# @param field_name_direction_pairs [Array<(String, Symbol)>] pairs of field names and `:asc` or `:desc`
+# @return [void]
+#
+# @example Sort on `name` (ascending) with `createdAt` (descending) as a tie-breaker
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Campaign" do |t|
+# t.field "id", "ID!"
+# t.field "name", "String"
+# t.field "createdAt", "DateTime"
+#
+# t.index "campaigns"do |i|
+# i.default_sort "name", :asc, "createdAt", :desc
+# end
+# end
+# end
+defdefault_sort(*field_name_direction_pairs)
+ self.default_sort_pairs=field_name_direction_pairs
+ end
+
+ # Causes this index to "rollover" at the provided `frequency` based on the value of the provided `timestamp_field_path_name`.
+# This is particularly useful for time-series data. Partitioning the data into `hourly`, `daily`, `monthly` or `yearly` buckets
+# allows for different index configurations, and can be necessary when a dataset is too large to fit in one dataset given
+# Elasticsearch/OpenSearch limitations on the number of shards in one index. In addition, ElasticGraph optimizes queries which
+# filter on the timestamp field to target the subset of the indices in which matching documents could reside.
+#
+# @note the timestamp field specified here **must be immutable**. To understand why, consider a `:yearly` rollover
+# index used for data based on `createdAt`; if ElasticGraph ingests record `123` with a createdAt of `2023-12-31T23:59:59Z`, it
+# will be indexed in the `2023` index. Later if it receives an update event for record `123` with a `createdAt` of
+# `2024-01-01T00:00:00Z` (a mere one second later!), ElasticGraph will store the new version of the payment in the `2024` index,
+# and leave the old copy of the payment in the `2023` index unchanged. It’ll have duplicates for that document.
+# @note changing the `rollover` configuration on an existing index that already has data will result in duplicate documents
+#
+# @param frequency [:yearly, :monthly, :daily, :hourly] how often to rollover the index
+# @param timestamp_field_path_name [String] dot-separated path to the timestamp field used for rollover. Note: all referenced
+# fields must exist when this is called.
+# @return [void]
+#
+# @example Define a `campaigns` index to rollover yearly based on `createdAt`
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Campaign" do |t|
+# t.field "id", "ID!"
+# t.field "name", "String"
+# t.field "createdAt", "DateTime"
+#
+# t.index "campaigns"do |i|
+# i.rollover :yearly, "createdAt"
+# end
+# end
+# end
+defrollover(frequency,timestamp_field_path_name)
+ timestamp_field_path=public_field_path(timestamp_field_path_name,explanation:"it is referenced as an index `rollover` field")
+
+ unlessdate_and_datetime_types.include?(timestamp_field_path.type.fully_unwrapped.name)
+ date_or_datetime_description=date_and_datetime_types.map{|t|"`#{t}`"}.join(" or ")
+ raiseErrors::SchemaError,"rollover field `#{timestamp_field_path.full_description}` cannot be used for rollover since it is not a #{date_or_datetime_description} field."
+ end
+
+ iftimestamp_field_path.type.list?
+ raiseErrors::SchemaError,"rollover field `#{timestamp_field_path.full_description}` cannot be used for rollover since it is a list field."
+ end
+
+ timestamp_field_path.path_parts.each{|f|f.json_schemanullable:false}
+
+ self.rollover_config=RolloverConfig.new(
+ frequency:frequency,
+ timestamp_field_path:timestamp_field_path
+ )
+ end
+
+ # Configures the index to [route documents to shards](https://www.elastic.co/guide/en/elasticsearch/reference/8.15/mapping-routing-field.html)
+# based on the specified field. ElasticGraph optimizes queries that filter on the shard routing field so that they only run on a
+# subset of nodes instead of all nodes. This can make a big difference in query performance if queries usually filter on a certain
+# field. Using an appropriate field for shard routing is often essential for horizontal scaling, as it avoids having every query
+# hit every node, allowing additional nodes to increase query throughput.
+#
+# @note it is essential that the shards are well-balanced. If the data’s distribution is lopsided, using this feature can make
+# performance worse.
+# @note the routing field specified here **must be immutable**. If ElasticGraph receives an updated version of a document with a
+# different routing value, it’ll write the new version of the document to a different shard and leave the copy on the old shard
+# unchanged, leading to duplicates.
+# @note changing the shard routing configuration on an existing index that already has data will result in duplicate documents
+#
+# @param routing_field_path_name [String] dot-separated path to the field used for shard routing. Note: all referenced
+# fields must exist when this is called.
+# @return [void]
+#
+# @example Define a `campaigns` index to shard on `organizationId`
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Campaign" do |t|
+# t.field "id", "ID!"
+# t.field "name", "String"
+# t.field "organizationId", "ID"
+#
+# t.index "campaigns"do |i|
+# i.route_with "organizationId"
+# end
+# end
+# end
+defroute_with(routing_field_path_name)
+ routing_field_path=public_field_path(routing_field_path_name,explanation:"it is referenced as an index `route_with` field")
+
+ unlessrouting_field_path.type.leaf?
+ raiseErrors::SchemaError,"shard routing field `#{routing_field_path.full_description}` cannot be used for routing since it is not a leaf field."
+ end
+
+ self.routing_field_path=routing_field_path
+
+ routing_field_path.path_parts[0..-2].each{|f|f.json_schemanullable:false}
+ routing_field_path.last_part.json_schemanullable:false,pattern:HAS_NON_WHITE_SPACE_REGEX
+ indexed_type.append_to_documentation"For more performant queries on this type, please filter on `#{routing_field_path_name}` if possible."
+ end
+
+ # @see #route_with
+# @return [Boolean] whether or not this index uses custom shard routing
+defuses_custom_routing?
+ routing_field_path.path_in_index!="id"
+ end
+
+ # @return [Hash<String, Object>] datastore configuration for this index for when it does not use rollover
+defto_index_config
+ {
+ "aliases"=>{},
+ "mappings"=>mappings,
+ "settings"=>settings
+ }.compact
+ end
+
+ # @return [Hash<String, Object>] datastore configuration for the index template that will be defined if rollover is used
+defto_index_template_config
+ {
+ "index_patterns"=>["#{name}#{ROLLOVER_INDEX_INFIX_MARKER}*"],
+ "template"=>{
+ "aliases"=>{},
+ "mappings"=>mappings,
+ "settings"=>settings
+ }
+ }
+ end
+
+ # @return [SchemaArtifacts::RuntimeMetadata::IndexDefinition] runtime metadata for this index
+defruntime_metadata
+ SchemaArtifacts::RuntimeMetadata::IndexDefinition.new(
+ route_with:routing_field_path.path_in_index,
+ rollover:rollover_config&.runtime_metadata,
+ current_sources:indexed_type.current_sources,
+ fields_by_path:indexed_type.index_field_runtime_metadata_tuples.to_h,
+ default_sort_fields:default_sort_pairs.each_slice(2).mapdo|(graphql_field_path_name,direction)|
+ SchemaArtifacts::RuntimeMetadata::SortField.new(
+ field_path:public_field_path(graphql_field_path_name,explanation:"it is referenced as an index `default_sort` field").path_in_index,
+ direction:direction
+ )
+ end
+ )
+ end
+
+ private
+
+ # A regex that requires at least one non-whitespace character.
+# Note: this does not use the `/S` character class because it's recommended to use a small subset
+# of Regex syntax:
+#
+# > The regular expression syntax used is from JavaScript (ECMA 262, specifically). However, that
+# > complete syntax is not widely supported, therefore it is recommended that you stick to the subset
+# > of that syntax described below.
+#
+# (From https://json-schema.org/understanding-json-schema/reference/regular_expressions.html)
+HAS_NON_WHITE_SPACE_REGEX="[^ \t\n]+"
+
+ DEFAULT_SETTINGS={
+ "index.mapping.ignore_malformed"=>false,
+ "index.mapping.coerce"=>false,
+ "index.number_of_replicas"=>1,
+ "index.number_of_shards"=>1
+ }
+
+ defmappings
+ field_mappings=indexed_type
+ .to_indexing_field_type
+ .to_mapping
+ .except("type")# `type` is invalid at the mapping root because it always has to be an object.
+.then{|mapping|ListCountsMapping.merged_into(mapping,for_type:indexed_type)}
+ .thendo|fm|
+ Support::HashUtil.deep_merge(fm,{"properties"=>{
+ "__sources"=>{"type"=>"keyword"},
+ "__versions"=>{
+ "type"=>"object",
+ # __versions is map keyed by relationship name, with values that are maps keyed by id. Since it's not
+# a static object with known fields, we need to use dynamic here. Passing `false` allows some level
+# of dynamicness. As per https://www.elastic.co/guide/en/elasticsearch/reference/8.7/dynamic.html#dynamic-parameters:
+#
+# > New fields are ignored. These fields will not be indexed or searchable, but will still appear in the _source
+# > field of returned hits. These fields will not be added to the mapping, and new fields must be added explicitly.
+#
+# We need `__versions` to be in `_source` (so that our update scripts can operate on it), but
+# have no need for it to be searchable (as it's just an internal data structure used for indexing).
+#
+# Note: we intentionally set false as a string here, because that's how the datastore echoes it back
+# to us when you query the mapping (even if you set it as a boolean). Our checks for index mapping
+# consistency fail validation if we set it as a boolean since the datastore doesn't echo it back as
+# a boolean.
+"dynamic"=>"false"
+ }
+ }})
+ end
+
+ {"dynamic"=>"strict"}.merge(field_mappings).tapdo|hash|
+ # If we are using custom shard routing, we want to require a `routing` value to be provided
+# in every single index, get, delete or update request; otherwise the request might be
+# made against the wrong shard.
+hash["_routing"]={"required"=>true}ifuses_custom_routing?
+ hash["_size"]={"enabled"=>true}ifschema_def_state.index_document_sizes?
+ end
+ end
+
+ defpublic_field_path(public_path_string,explanation:)
+ parent_is_not_list=->(parent_field){!parent_field.type.list?}
+ resolver=SchemaElements::FieldPath::Resolver.new
+ resolved_path=resolver.resolve_public_path(indexed_type,public_path_string,&parent_is_not_list)
+ returnresolved_pathifresolved_path
+
+ path_parts=public_path_string.split(".")
+ error_msg="Field `#{indexed_type.name}.#{public_path_string}` cannot be resolved, but #{explanation}."
+
+ # If it is a nested field path, the problem could be that a type has been referenced which does not exist, so mention that.
+ifpath_parts.size>1
+ error_msg+=" Verify that all fields and types referenced by `#{public_path_string}` are defined."
+ end
+
+ # If the first part of the path doesn't resolve, the problem could be that the field is defined after the `index` call
+# but it needs to be defined before it, so mention that.
+ifresolver.resolve_public_path(indexed_type,path_parts.first,&parent_is_not_list).nil?
+ error_msg+=" Note: the `#{indexed_type.name}.#{path_parts.first}` definition must come before the `index` call."
+ end
+
+ raiseErrors::SchemaError,error_msg
+ end
+
+ defdate_and_datetime_types
+ @date_and_datetime_types||=%w[DateDateTime].mapdo|type|
+ schema_def_state.type_namer.name_for(type)
+ end
+ end
+end
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/indexing/index.rb', line 39
+
+classIndex<Struct.new(:name,:default_sort_pairs,:settings,:schema_def_state,:indexed_type,:routing_field_path,:rollover_config)
+ includeMixins::HasReadableToSAndInspect.new{|i|i.name}
+
+ # @param name [String] name of the index
+# @param settings [Hash<(String, Object)>] datastore settings for the index
+# @param schema_def_state [State] schema definition state
+# @param indexed_type [SchemaElements::ObjectType, SchemaElements::InterfaceType, SchemaElements::UnionType] type backed by this index
+# @yield [Index] the index, for further customization
+# @api private
+definitialize(name,settings,schema_def_state,indexed_type)
+ ifname.include?(ROLLOVER_INDEX_INFIX_MARKER)
+ raiseErrors::SchemaError,"`#{name}` is an invalid index definition name since it contains " \
+ "`#{ROLLOVER_INDEX_INFIX_MARKER}` which ElasticGraph treats as special."
+ end
+
+ settings=DEFAULT_SETTINGS.merge(Support::HashUtil.flatten_and_stringify_keys(settings,prefix:"index"))
+
+ super(name,[],settings,schema_def_state,indexed_type,[],nil)
+
+ # `id` is the field Elasticsearch/OpenSearch use for routing by default:
+# https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-routing-field.html
+# By using it here, it will cause queries to pass a `routing` parameter when
+# searching with id filtering on an index that does not use custom shard routing, giving
+# us a nice efficiency boost.
+self.routing_field_path=public_field_path("id",explanation:"indexed types must have an `id` field")
+
+ yieldselfifblock_given?
+ end
+
+ # Specifies how documents in this index should sort by default, when no `orderBy` argument is provided to the GraphQL query.
+#
+# @note the field name strings can be a dot-separated nested fields, but all referenced
+# fields must exist when this is called.
+#
+# @param field_name_direction_pairs [Array<(String, Symbol)>] pairs of field names and `:asc` or `:desc`
+# @return [void]
+#
+# @example Sort on `name` (ascending) with `createdAt` (descending) as a tie-breaker
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Campaign" do |t|
+# t.field "id", "ID!"
+# t.field "name", "String"
+# t.field "createdAt", "DateTime"
+#
+# t.index "campaigns"do |i|
+# i.default_sort "name", :asc, "createdAt", :desc
+# end
+# end
+# end
+defdefault_sort(*field_name_direction_pairs)
+ self.default_sort_pairs=field_name_direction_pairs
+ end
+
+ # Causes this index to "rollover" at the provided `frequency` based on the value of the provided `timestamp_field_path_name`.
+# This is particularly useful for time-series data. Partitioning the data into `hourly`, `daily`, `monthly` or `yearly` buckets
+# allows for different index configurations, and can be necessary when a dataset is too large to fit in one dataset given
+# Elasticsearch/OpenSearch limitations on the number of shards in one index. In addition, ElasticGraph optimizes queries which
+# filter on the timestamp field to target the subset of the indices in which matching documents could reside.
+#
+# @note the timestamp field specified here **must be immutable**. To understand why, consider a `:yearly` rollover
+# index used for data based on `createdAt`; if ElasticGraph ingests record `123` with a createdAt of `2023-12-31T23:59:59Z`, it
+# will be indexed in the `2023` index. Later if it receives an update event for record `123` with a `createdAt` of
+# `2024-01-01T00:00:00Z` (a mere one second later!), ElasticGraph will store the new version of the payment in the `2024` index,
+# and leave the old copy of the payment in the `2023` index unchanged. It’ll have duplicates for that document.
+# @note changing the `rollover` configuration on an existing index that already has data will result in duplicate documents
+#
+# @param frequency [:yearly, :monthly, :daily, :hourly] how often to rollover the index
+# @param timestamp_field_path_name [String] dot-separated path to the timestamp field used for rollover. Note: all referenced
+# fields must exist when this is called.
+# @return [void]
+#
+# @example Define a `campaigns` index to rollover yearly based on `createdAt`
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Campaign" do |t|
+# t.field "id", "ID!"
+# t.field "name", "String"
+# t.field "createdAt", "DateTime"
+#
+# t.index "campaigns"do |i|
+# i.rollover :yearly, "createdAt"
+# end
+# end
+# end
+defrollover(frequency,timestamp_field_path_name)
+ timestamp_field_path=public_field_path(timestamp_field_path_name,explanation:"it is referenced as an index `rollover` field")
+
+ unlessdate_and_datetime_types.include?(timestamp_field_path.type.fully_unwrapped.name)
+ date_or_datetime_description=date_and_datetime_types.map{|t|"`#{t}`"}.join(" or ")
+ raiseErrors::SchemaError,"rollover field `#{timestamp_field_path.full_description}` cannot be used for rollover since it is not a #{date_or_datetime_description} field."
+ end
+
+ iftimestamp_field_path.type.list?
+ raiseErrors::SchemaError,"rollover field `#{timestamp_field_path.full_description}` cannot be used for rollover since it is a list field."
+ end
+
+ timestamp_field_path.path_parts.each{|f|f.json_schemanullable:false}
+
+ self.rollover_config=RolloverConfig.new(
+ frequency:frequency,
+ timestamp_field_path:timestamp_field_path
+ )
+ end
+
+ # Configures the index to [route documents to shards](https://www.elastic.co/guide/en/elasticsearch/reference/8.15/mapping-routing-field.html)
+# based on the specified field. ElasticGraph optimizes queries that filter on the shard routing field so that they only run on a
+# subset of nodes instead of all nodes. This can make a big difference in query performance if queries usually filter on a certain
+# field. Using an appropriate field for shard routing is often essential for horizontal scaling, as it avoids having every query
+# hit every node, allowing additional nodes to increase query throughput.
+#
+# @note it is essential that the shards are well-balanced. If the data’s distribution is lopsided, using this feature can make
+# performance worse.
+# @note the routing field specified here **must be immutable**. If ElasticGraph receives an updated version of a document with a
+# different routing value, it’ll write the new version of the document to a different shard and leave the copy on the old shard
+# unchanged, leading to duplicates.
+# @note changing the shard routing configuration on an existing index that already has data will result in duplicate documents
+#
+# @param routing_field_path_name [String] dot-separated path to the field used for shard routing. Note: all referenced
+# fields must exist when this is called.
+# @return [void]
+#
+# @example Define a `campaigns` index to shard on `organizationId`
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Campaign" do |t|
+# t.field "id", "ID!"
+# t.field "name", "String"
+# t.field "organizationId", "ID"
+#
+# t.index "campaigns"do |i|
+# i.route_with "organizationId"
+# end
+# end
+# end
+defroute_with(routing_field_path_name)
+ routing_field_path=public_field_path(routing_field_path_name,explanation:"it is referenced as an index `route_with` field")
+
+ unlessrouting_field_path.type.leaf?
+ raiseErrors::SchemaError,"shard routing field `#{routing_field_path.full_description}` cannot be used for routing since it is not a leaf field."
+ end
+
+ self.routing_field_path=routing_field_path
+
+ routing_field_path.path_parts[0..-2].each{|f|f.json_schemanullable:false}
+ routing_field_path.last_part.json_schemanullable:false,pattern:HAS_NON_WHITE_SPACE_REGEX
+ indexed_type.append_to_documentation"For more performant queries on this type, please filter on `#{routing_field_path_name}` if possible."
+ end
+
+ # @see #route_with
+# @return [Boolean] whether or not this index uses custom shard routing
+defuses_custom_routing?
+ routing_field_path.path_in_index!="id"
+ end
+
+ # @return [Hash<String, Object>] datastore configuration for this index for when it does not use rollover
+defto_index_config
+ {
+ "aliases"=>{},
+ "mappings"=>mappings,
+ "settings"=>settings
+ }.compact
+ end
+
+ # @return [Hash<String, Object>] datastore configuration for the index template that will be defined if rollover is used
+defto_index_template_config
+ {
+ "index_patterns"=>["#{name}#{ROLLOVER_INDEX_INFIX_MARKER}*"],
+ "template"=>{
+ "aliases"=>{},
+ "mappings"=>mappings,
+ "settings"=>settings
+ }
+ }
+ end
+
+ # @return [SchemaArtifacts::RuntimeMetadata::IndexDefinition] runtime metadata for this index
+defruntime_metadata
+ SchemaArtifacts::RuntimeMetadata::IndexDefinition.new(
+ route_with:routing_field_path.path_in_index,
+ rollover:rollover_config&.runtime_metadata,
+ current_sources:indexed_type.current_sources,
+ fields_by_path:indexed_type.index_field_runtime_metadata_tuples.to_h,
+ default_sort_fields:default_sort_pairs.each_slice(2).mapdo|(graphql_field_path_name,direction)|
+ SchemaArtifacts::RuntimeMetadata::SortField.new(
+ field_path:public_field_path(graphql_field_path_name,explanation:"it is referenced as an index `default_sort` field").path_in_index,
+ direction:direction
+ )
+ end
+ )
+ end
+
+ private
+
+ # A regex that requires at least one non-whitespace character.
+# Note: this does not use the `/S` character class because it's recommended to use a small subset
+# of Regex syntax:
+#
+# > The regular expression syntax used is from JavaScript (ECMA 262, specifically). However, that
+# > complete syntax is not widely supported, therefore it is recommended that you stick to the subset
+# > of that syntax described below.
+#
+# (From https://json-schema.org/understanding-json-schema/reference/regular_expressions.html)
+HAS_NON_WHITE_SPACE_REGEX="[^ \t\n]+"
+
+ DEFAULT_SETTINGS={
+ "index.mapping.ignore_malformed"=>false,
+ "index.mapping.coerce"=>false,
+ "index.number_of_replicas"=>1,
+ "index.number_of_shards"=>1
+ }
+
+ defmappings
+ field_mappings=indexed_type
+ .to_indexing_field_type
+ .to_mapping
+ .except("type")# `type` is invalid at the mapping root because it always has to be an object.
+.then{|mapping|ListCountsMapping.merged_into(mapping,for_type:indexed_type)}
+ .thendo|fm|
+ Support::HashUtil.deep_merge(fm,{"properties"=>{
+ "__sources"=>{"type"=>"keyword"},
+ "__versions"=>{
+ "type"=>"object",
+ # __versions is map keyed by relationship name, with values that are maps keyed by id. Since it's not
+# a static object with known fields, we need to use dynamic here. Passing `false` allows some level
+# of dynamicness. As per https://www.elastic.co/guide/en/elasticsearch/reference/8.7/dynamic.html#dynamic-parameters:
+#
+# > New fields are ignored. These fields will not be indexed or searchable, but will still appear in the _source
+# > field of returned hits. These fields will not be added to the mapping, and new fields must be added explicitly.
+#
+# We need `__versions` to be in `_source` (so that our update scripts can operate on it), but
+# have no need for it to be searchable (as it's just an internal data structure used for indexing).
+#
+# Note: we intentionally set false as a string here, because that's how the datastore echoes it back
+# to us when you query the mapping (even if you set it as a boolean). Our checks for index mapping
+# consistency fail validation if we set it as a boolean since the datastore doesn't echo it back as
+# a boolean.
+"dynamic"=>"false"
+ }
+ }})
+ end
+
+ {"dynamic"=>"strict"}.merge(field_mappings).tapdo|hash|
+ # If we are using custom shard routing, we want to require a `routing` value to be provided
+# in every single index, get, delete or update request; otherwise the request might be
+# made against the wrong shard.
+hash["_routing"]={"required"=>true}ifuses_custom_routing?
+ hash["_size"]={"enabled"=>true}ifschema_def_state.index_document_sizes?
+ end
+ end
+
+ defpublic_field_path(public_path_string,explanation:)
+ parent_is_not_list=->(parent_field){!parent_field.type.list?}
+ resolver=SchemaElements::FieldPath::Resolver.new
+ resolved_path=resolver.resolve_public_path(indexed_type,public_path_string,&parent_is_not_list)
+ returnresolved_pathifresolved_path
+
+ path_parts=public_path_string.split(".")
+ error_msg="Field `#{indexed_type.name}.#{public_path_string}` cannot be resolved, but #{explanation}."
+
+ # If it is a nested field path, the problem could be that a type has been referenced which does not exist, so mention that.
+ifpath_parts.size>1
+ error_msg+=" Verify that all fields and types referenced by `#{public_path_string}` are defined."
+ end
+
+ # If the first part of the path doesn't resolve, the problem could be that the field is defined after the `index` call
+# but it needs to be defined before it, so mention that.
+ifresolver.resolve_public_path(indexed_type,path_parts.first,&parent_is_not_list).nil?
+ error_msg+=" Note: the `#{indexed_type.name}.#{path_parts.first}` definition must come before the `index` call."
+ end
+
+ raiseErrors::SchemaError,error_msg
+ end
+
+ defdate_and_datetime_types
+ @date_and_datetime_types||=%w[DateDateTime].mapdo|type|
+ schema_def_state.type_namer.name_for(type)
+ end
+ end
+end
the timestamp field specified here must be immutable. To understand why, consider a :yearly rollover
+index used for data based on createdAt; if ElasticGraph ingests record 123 with a createdAt of 2023-12-31T23:59:59Z, it
+will be indexed in the 2023 index. Later if it receives an update event for record 123 with a createdAt of
+2024-01-01T00:00:00Z (a mere one second later!), ElasticGraph will store the new version of the payment in the 2024 index,
+and leave the old copy of the payment in the 2023 index unchanged. It’ll have duplicates for that document.
+
+
+
+
+ Note:
+
changing the rollover configuration on an existing index that already has data will result in duplicate documents
+
+
+
+
This method returns an undefined value.
Causes this index to “rollover” at the provided frequency based on the value of the provided timestamp_field_path_name.
+This is particularly useful for time-series data. Partitioning the data into hourly, daily, monthly or yearly buckets
+allows for different index configurations, and can be necessary when a dataset is too large to fit in one dataset given
+Elasticsearch/OpenSearch limitations on the number of shards in one index. In addition, ElasticGraph optimizes queries which
+filter on the timestamp field to target the subset of the indices in which matching documents could reside.
+
+
+
+
+
+
+
+
Examples:
+
+
+
Define a campaigns index to rollover yearly based on createdAt
+
+
+
ElasticGraph.define_schemado|schema|
+ schema.object_type"Campaign"do|t|
+ t.field"id","ID!"
+ t.field"name","String"
+ t.field"createdAt","DateTime"
+
+ t.index"campaigns"do|i|
+ i.rollover:yearly,"createdAt"
+ end
+ end
+end
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/indexing/index.rb', line 122
+
+defrollover(frequency,timestamp_field_path_name)
+ timestamp_field_path=public_field_path(timestamp_field_path_name,explanation:"it is referenced as an index `rollover` field")
+
+ unlessdate_and_datetime_types.include?(timestamp_field_path.type.fully_unwrapped.name)
+ date_or_datetime_description=date_and_datetime_types.map{|t|"`#{t}`"}.join(" or ")
+ raiseErrors::SchemaError,"rollover field `#{timestamp_field_path.full_description}` cannot be used for rollover since it is not a #{date_or_datetime_description} field."
+ end
+
+ iftimestamp_field_path.type.list?
+ raiseErrors::SchemaError,"rollover field `#{timestamp_field_path.full_description}` cannot be used for rollover since it is a list field."
+ end
+
+ timestamp_field_path.path_parts.each{|f|f.json_schemanullable:false}
+
+ self.rollover_config=RolloverConfig.new(
+ frequency:frequency,
+ timestamp_field_path:timestamp_field_path
+ )
+end
it is essential that the shards are well-balanced. If the data’s distribution is lopsided, using this feature can make
+performance worse.
+
+
+
+
+ Note:
+
the routing field specified here must be immutable. If ElasticGraph receives an updated version of a document with a
+different routing value, it’ll write the new version of the document to a different shard and leave the copy on the old shard
+unchanged, leading to duplicates.
+
+
+
+
+ Note:
+
changing the shard routing configuration on an existing index that already has data will result in duplicate documents
+
+
+
+
This method returns an undefined value.
Configures the index to route documents to shards
+based on the specified field. ElasticGraph optimizes queries that filter on the shard routing field so that they only run on a
+subset of nodes instead of all nodes. This can make a big difference in query performance if queries usually filter on a certain
+field. Using an appropriate field for shard routing is often essential for horizontal scaling, as it avoids having every query
+hit every node, allowing additional nodes to increase query throughput.
+
+
+
+
+
+
+
+
Examples:
+
+
+
Define a campaigns index to shard on organizationId
+
+
+
ElasticGraph.define_schemado|schema|
+ schema.object_type"Campaign"do|t|
+ t.field"id","ID!"
+ t.field"name","String"
+ t.field"organizationId","ID"
+
+ t.index"campaigns"do|i|
+ i.route_with"organizationId"
+ end
+ end
+end
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/indexing/index.rb', line 171
+
+defroute_with(routing_field_path_name)
+ routing_field_path=public_field_path(routing_field_path_name,explanation:"it is referenced as an index `route_with` field")
+
+ unlessrouting_field_path.type.leaf?
+ raiseErrors::SchemaError,"shard routing field `#{routing_field_path.full_description}` cannot be used for routing since it is not a leaf field."
+ end
+
+ self.routing_field_path=routing_field_path
+
+ routing_field_path.path_parts[0..-2].each{|f|f.json_schemanullable:false}
+ routing_field_path.last_part.json_schemanullable:false,pattern:HAS_NON_WHITE_SPACE_REGEX
+ indexed_type.append_to_documentation"For more performant queries on this type, please filter on `#{routing_field_path_name}` if possible."
+end
Hash form of the metadata that can be dumped in JSON schema.
+
+
+
+
+
+
+
+
+
+
+
+
Instance Attribute Details
+
+
+
+
+
+
+ #name_in_index ⇒ String(readonly)
+
+
+
+
+
+
+
+
Returns name of the field in the index.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String)
+
+
+
+ —
+
name of the field in the index
+
+
+
+
+
+
+
+
+
+
+
+
+24
+25
+26
+27
+28
+29
+30
+31
+
+
+
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/indexing/json_schema_field_metadata.rb', line 24
+
+classJSONSchemaFieldMetadata<::Data
+ # @return [Hash<String, String>] hash form of the metadata that can be dumped in JSON schema
+defto_dumpable_hash
+ {"type"=>type,"nameInIndex"=>name_in_index}
+ end
+
+ # @dynamic initialize, type, name_in_index
+end
+
+
+
+
+
+
+
+
+
+
+ #type ⇒ String(readonly)
+
+
+
+
+
+
+
+
Returns name of the ElasticGraph type for this field.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String)
+
+
+
+ —
+
name of the ElasticGraph type for this field
+
+
+
+
+
+
+
+
+
+
+
+
+24
+25
+26
+27
+28
+29
+30
+31
+
+
+
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/indexing/json_schema_field_metadata.rb', line 24
+
+classJSONSchemaFieldMetadata<::Data
+ # @return [Hash<String, String>] hash form of the metadata that can be dumped in JSON schema
+defto_dumpable_hash
+ {"type"=>type,"nameInIndex"=>name_in_index}
+ end
+
+ # @dynamic initialize, type, name_in_index
+end
Namespace for modules that are used as mixins. Mixins are used to offer a consistent API for
+schema definition features that apply to multiple types of schema elements.
Mixin that supports the customization of derived GraphQL types.
+
+
For each type you define, ElasticGraph generates a number of derived GraphQL types that are needed to facilitate the ElasticGraph
+Query API. Methods in this module can be used to customize those derived GraphQL types.
Registers a customization block for the named fields on the named derived GraphQL type. The provided block will get run on the
+named fields of the named derived GraphQL type, allowing them to be customized.
+
+
+
+
+
+
+
+
Examples:
+
+
+
Customize named fields of a derived GraphQL type
+
+
+
ElasticGraph.define_schemado|schema|
+ schema.object_type"Campaign"do|t|
+ t.field"id","ID!"
+ t.index"campaigns"
+
+ t.customize_derived_type_fields"CampaignConnection","pageInfo","totalEdgeCount"do|dt|
+ # Add a `@deprecated` directive to `CampaignConnection.pageInfo` and `CampaignConnection.totalEdgeCount`.
+dt.directive"deprecated"
+ end
+ end
+end
+
+
+
Parameters:
+
+
+
+
+ type_name
+
+
+ (String)
+
+
+
+ —
+
name of the derived type containing fields you want to customize
+
+
+
+
+
+
+ field_names
+
+
+ (Array<String>)
+
+
+
+ —
+
names of the fields on the derived types that you wish to customize
+
+
+
+
+
+
+
+
+
+
+
+
+
+77
+78
+79
+80
+81
+82
+83
+
+
+
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/mixins/has_derived_graphql_type_customizations.rb', line 77
+
+defcustomize_derived_type_fields(type_name,*field_names,&customization_block)
+ customizations_by_field=derived_field_customizations_by_type_and_field_name[type_name]
+
+ field_names.eachdo|field_name|
+ customizations_by_field[field_name]<<customization_block
+ end
+end
Registers a customization block for the named derived graphql types. The provided block will get run on the named derived GraphQL
+types, allowing them to be customized.
+
+
+
+
+
+
+
+
Examples:
+
+
+
Customize named derived GraphQL types
+
+
+
ElasticGraph.define_schemado|schema|
+ schema.object_type"Campaign"do|t|
+ t.field"id","ID!"
+ t.index"campaigns"
+
+ t.customize_derived_types"CampaignFilterInput","CampaignSortOrderInput"do|dt|
+ # Add a `@deprecated` directive to two specific derived types.
+dt.directive"deprecated"
+ end
+ end
+end
+
+
+
Customize all derived GraphQL types
+
+
+
ElasticGraph.define_schemado|schema|
+ schema.object_type"Campaign"do|t|
+ t.field"id","ID!"
+ t.index"campaigns"
+
+ t.customize_derived_types:alldo|dt|
+ # Add a `@deprecated` directive to all derived types.
+dt.directive"deprecated"
+ end
+ end
+end
If you’re using a custom directive rather than a standard GraphQL directive like @deprecated, you’ll also need to use
+API#raw_sdl to define the custom directive.
+
+
+
+
This method returns an undefined value.
Adds a GraphQL directive to the current schema element.
+
+
+
+
+
+
+
+
Examples:
+
+
+
Add a standard GraphQL directive to a field
+
+
+
ElasticGraph.define_schemado|schema|
+ schema.object_type"Campaign"do|t|
+ t.field"id","ID"do|f|
+ f.directive"deprecated"
+ end
+ end
+end
+
+
+
Define a custom GraphQL directive and add it to an object type
+
+
+
ElasticGraph.define_schemado|schema|
+ # Define a directive we can use to annotate what system a data type comes from.
+schema.raw_sdl"directive @sourcedFrom(system: String!) on OBJECT"
+
+ schema.object_type"Campaign"do|t|
+ t.field"id","ID"
+ t.directive"sourcedFrom",system:"campaigns"
+ end
+end
Define documentation on an object type and on a field
+
+
+
ElasticGraph.define_schemado|schema|
+ schema.object_type"Campaign"do|t|
+ t.documentation"A marketing campaign."
+
+ t.field"id","ID"do|f|
+ f.documentation<<~EOS
+ The identifier of the campaign.
+
+ Note: this is randomly generated.
+ EOS
+end
+ end
+end
+
+
+
Parameters:
+
+
+
+
+ comment
+
+
+ (String)
+
+
+
+ —
+
the documentation string
+
+
+
+
+
+
+
+
+
+
+
+
+
+38
+39
+40
+
+
+
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/mixins/has_documentation.rb', line 38
+
+defdocumentation(comment)
+ self.doc_comment=comment
+end
+
+
+
+
+
+
+
+
+ #formatted_documentation ⇒ String
+
+
+
+
+
+
+
+
Formats the documentation using GraphQL SDL syntax.
Configures the ElasticGraph indexer to derive another type from this indexed type, using the from_id field as the source of the id of the derived type, and the provided block for the definitions of the derived fields.
Converts the current type from being an embedded type (that is, a type that is embedded within another indexed type) to an indexed type that resides in the named index definition.
Configures the ElasticGraph indexer to derive another type from this indexed type, using the from_id field as
+the source of the id of the derived type, and the provided block for the definitions of the derived fields.
+
+
+
+
+
+
+
+
Examples:
+
+
+
Derive a Course type from StudentCourseEnrollment events
+
+
+
ElasticGraph.define_schemado|schema|
+ # `StudentCourseEnrollment` is a directly indexed type.
+schema.object_type"StudentCourseEnrollment"do|t|
+ t.field"id","ID"
+ t.field"courseId","ID"
+ t.field"courseName","String"
+ t.field"studentName","String"
+ t.field"courseStartDate","Date"
+
+ t.index"student_course_enrollments"
+
+ # Here we define how the `Course` indexed type is derived when we index `StudentCourseEnrollment` events.
+t.derive_indexed_type_fields"Course",from_id:"courseId"do|derive|
+ # `derive` is an instance of `DerivedIndexedType`.
+derive.immutable_value"name",from:"courseName"
+ derive.append_only_set"students",from:"studentName"
+ derive.min_value"firstOfferedDate",from:"courseStartDate"
+ derive.max_value"mostRecentlyOfferedDate",from:"courseStartDate"
+ end
+ end
+
+ # `Course` is an indexed type that is derived entirely from `StudentCourseEnrollment` events.
+schema.object_type"Course"do|t|
+ t.field"id","ID"
+ t.field"name","String"
+ t.field"students","[String!]!"
+ t.field"firstOfferedDate","Date"
+ t.field"mostRecentlyOfferedDate","Date"
+
+ t.index"courses"
+ end
+end
+
+
+
Parameters:
+
+
+
+
+ name
+
+
+ (String)
+
+
+
+ —
+
name of the derived type
+
+
+
+
+
+
+ from_id
+
+
+ (String)
+
+
+
+ —
+
path to the source type field with id values for the derived type
Use #root_query_fields on indexed types to name the field that will be exposed on Query.
+
+
+
+
+ Note:
+
Indexed types must also define an id field, which ElasticGraph will use as the primary key.
+
+
+
+
+ Note:
+
Datastore index settings can also be defined (or overridden) in an environment-specific settings YAML file. Index settings
+that you want to configure differently for different environments (such as index.number_of_shards—-production and staging
+will probably need different numbers!) should be configured in the per-environment YAML configuration files rather than here.
+
+
+
+
This method returns an undefined value.
Converts the current type from being an embedded type (that is, a type that is embedded within another indexed type) to an
+indexed type that resides in the named index definition. Indexed types are directly indexed into the datastore, and will be
+queryable from the root Query type.
+
+
+
+
+
+
+
+
Examples:
+
+
+
Define a campaigns index
+
+
+
ElasticGraph.define_schemado|schema|
+ schema.object_type"Campaign"do|t|
+ t.field"id","ID"
+
+ t.index(
+ "campaigns",
+ # Configure `index.refresh_interval`.
+refresh_interval:"1s",
+ # Use `index.search` to log warnings for any search query that take more than five seconds.
+search:{slowlog:{level:"WARN",threshold:{query:{warn:"5s"}}}}
+ )do|i|
+ # The index can be customized further here.
+end
+ end
+end
datastore index settings you want applied to every environment. See the Elasticsearch docs
+for a list of valid settings, but be sure to omit the index. prefix here.
Determines what the root Query fields will be to query this indexed type. In addition, this method accepts a block, which you
+can use to customize the root query field (such as adding a GraphQL directive to it).
+
+
+
+
+
+
+
+
Examples:
+
+
+
Set plural and singular names
+
+
+
ElasticGraph.define_schemado|schema|
+ schema.object_type"Person"do|t|
+ t.field"id","ID"
+
+ # Results in `Query.people` and `Query.personAggregations`.
+t.root_query_fieldsplural:"people",singular:"person"
+
+ t.index"people"
+ end
+end
+
+
+
Customize Query fields
+
+
+
ElasticGraph.define_schemado|schema|
+ schema.object_type"Person"do|t|
+ t.field"id","ID"
+
+ t.root_query_fieldsplural:"people",singular:"person"do|f|
+ # Marks `Query.people` and `Query.personAggregations` as deprecated.
+f.directive"deprecated"
+ end
+
+ t.index"people"
+ end
+end
+
+
+
Parameters:
+
+
+
+
+ plural
+
+
+ (String)
+
+
+
+ —
+
the plural name of the entity; used for the root Query field that queries documents of this indexed type
the singular name of the entity; used for the root Query field (with an Aggregations suffix) that
+queries aggregations of this indexed type. If not provided, will derive it from the type name (e.g. converting it to camelCase
+or snake_case, depending on configuration).
Returns the singular name of the entity; used for the root Query field (with an Aggregations suffix) that queries
+aggregations of this indexed type. If not provided, will derive it from the type name (e.g. converting it to camelCase or
+snake_case, depending on configuration).
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String)
+
+
+
+ —
+
the singular name of the entity; used for the root Query field (with an Aggregations suffix) that queries
+aggregations of this indexed type. If not provided, will derive it from the type name (e.g. converting it to camelCase or
+snake_case, depending on configuration).
+
+
+
+
+
+
+
+
+
+
+
+
+214
+215
+216
+
+
+
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/mixins/has_indices.rb', line 214
+
+defsingular_root_query_field_name
+ @singular_root_query_field_name||to_field_name(name)
+end
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/main/ElasticGraph/SchemaDefinition/Mixins/HasTypeInfo.html b/docs/main/ElasticGraph/SchemaDefinition/Mixins/HasTypeInfo.html
new file mode 100644
index 00000000..7a5fc293
--- /dev/null
+++ b/docs/main/ElasticGraph/SchemaDefinition/Mixins/HasTypeInfo.html
@@ -0,0 +1,662 @@
+
+
+
+
+
+
+ Module: ElasticGraph::SchemaDefinition::Mixins::HasTypeInfo
+
+ — Documentation by YARD 0.9.37
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Mixin used to specify non-GraphQL type info (datastore index and JSON schema type info).
+Exists as a mixin so we can apply the same consistent API to every place we need to use this.
+Currently it’s used in 3 places:
+
+
+
SchemaElements::ScalarType: allows specification of how scalars are represented in JSON schema and the index.
We recommend using JSON schema validations in a limited fashion. Validations that are appropriate to apply when data is
+entering the system-of-record are often not appropriate on a secondary index like ElasticGraph. Events that violate a JSON
+schema validation will fail to index (typically they will be sent to the dead letter queue and page an oncall engineer). If an
+ElasticGraph instance is meant to contain all the data of some source system, you probably don’t want it applying stricter
+validations than the source system itself has. We recommend limiting your JSON schema validations to situations where
+violations would prevent ElasticGraph from operating correctly.
+
+
+
+
This method returns an undefined value.
Defines the JSON schema validations for this field or type. Validations
+defined here will be included in the generated json_schemas.yaml artifact, which is used by the ElasticGraph indexer to
+validate events before indexing their data in the datastore. In addition, the publisher may use json_schemas.yaml for code
+generation and to apply validation before publishing an event to ElasticGraph.
+
+
Can be called multiple times; each time, the options will be merged into the existing options.
+
+
This is required on a SchemaElements::ScalarType (since we don’t know how a custom scalar type should be represented in
+JSON!). On a SchemaElements::Field, this is optional, but can be used to make the JSON schema validation stricter then it
+would otherwise be. For example, you could use json_schema maxLength: 30 on a String field to limit the length.
+
+
You can use any of the JSON schema validation keywords here. In addition, nullable: false is supported to configure the
+generated JSON schema to disallow null values for the field. Note that if you define a field with a non-nullable GraphQL type
+(e.g. Int!), the JSON schema will automatically disallow nulls. However, as explained in the
+SchemaElements::TypeWithSubfields#field documentation, we generally recommend against defining non-nullable GraphQL fields.
+json_schema nullable: false will disallow null values from being indexed, while still keeping the field nullable in the
+GraphQL schema. If you think you might want to make a field non-nullable in the GraphQL schema some day, it’s a good idea to use
+json_schema nullable: false now to ensure every indexed record has a non-null value for the field.
+
+
+
+
+
+
+
+
Examples:
+
+
+
Define the JSON schema validations of a custom scalar type
+
+
+
ElasticGraph.define_schemado|schema|
+ schema.scalar_type"URL"do|t|
+ t.mappingtype:"keyword"
+
+ # JSON schema has a built-in URI format validator:
+# https://json-schema.org/understanding-json-schema/reference/string.html#resource-identifiers
+t.json_schematype:"string",format:"uri"
+ end
+end
+
+
+
Define additional validations on a field
+
+
+
ElasticGraph.define_schemado|schema|
+ schema.object_type"Card"do|t|
+ t.field"id","ID!"
+
+ t.field"expYear","Int"do|f|
+ # Use JSON schema to ensure the publisher is sending us 4 digit years, not 2 digit years.
+f.json_schemaminimum:2000,maximum:2099
+ end
+
+ t.field"expMonth","Int"do|f|
+ f.json_schemaminimum:1,maximum:12
+ end
+
+ t.index"cards"
+ end
+end
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/mixins/has_type_info.rb', line 28
+
+defjson_schema_options
+ @json_schema_options||={}
+end
+
+
+
+
+
+
+
+
+ #mapping(**options) ⇒ void
+
+
+
+
+
+
+
+
This method returns an undefined value.
Defines the Elasticsearch/OpenSearch field mapping type
+and mapping parameters for a field or type.
+The options passed here will be included in the generated datastore_config.yaml artifact that ElasticGraph uses to configure
+Elasticsearch/OpenSearch.
+
+
Can be called multiple times; each time, the options will be merged into the existing options.
+
+
This is required on a SchemaElements::ScalarType; without it, ElasticGraph would have no way to know how the datatype should be
+indexed in the datastore.
+
+
On a SchemaElements::Field, this can be used to customize how a field is indexed. For example, String fields are normally
+indexed as keywords; to instead index a String
+field for full text search, you’d need to configure mapping type: "text".
+
+
On a SchemaElements::ObjectType, this can be used to use a specific Elasticsearch/OpenSearch data type for something that is
+modeled as an object in GraphQL. For example, we use it for the GeoLocation type so they get indexed in Elasticsearch using the
+geo_point type.
+
+
+
+
+
+
+
+
Examples:
+
+
+
Define the mapping of a custom scalar type
+
+
+
ElasticGraph.define_schemado|schema|
+ schema.scalar_type"URL"do|t|
+ t.mappingtype:"keyword"
+ t.json_schematype:"string",format:"uri"
+ end
+end
+
+
+
Customize the mapping of a field
+
+
+
ElasticGraph.define_schemado|schema|
+ schema.object_type"Card"do|t|
+ t.field"id","ID!"
+
+ t.field"cardholderName","String"do|f|
+ # index this field for full text search
+f.mappingtype:"text"
+ end
+
+ t.field"expYear","Int"do|f|
+ # Use a smaller numeric type to save space in the datastore
+f.mappingtype:"short"
+ f.json_schemaminimum:2000,maximum:2099
+ end
+
+ t.field"expMonth","Int"do|f|
+ # Use a smaller numeric type to save space in the datastore
+f.mappingtype:"byte"
+ f.json_schemaminimum:1,maximum:12
+ end
+
+ t.index"cards"
+ end
+end
Declares that the current type implements the specified interface, making the current type a subtype of the interface. The
+current type must define all of the fields of the named interface, with the exact same field types.
When enabled, ElasticGraph will configure the index mappings so that the datastore indexes a
+_size field in each document. ElasticGraph itself does not do anything with this field, but it will be available for your use
+in any direct queries (e.g. via Kibana). Important note: this requires the mapper-size
+plugin to be installed on your datastore cluster.
+You are responsible for ensuring that is installed if you enable this feature. If you enable this and the plugin is not
+installed, you will get errors!
overrides for specific names of schema elements (fields, arguments,
+directives) generated by ElasticGraph. For example, to rename the gt filter field to greaterThan, pass {gt: "greaterThan"}.
overrides for the naming formats used by ElasticGraph for derived GraphQL
+type names. For example, to use Metrics instead of AggregatedValues as the suffix for the generated types supporting
+getting aggregated metrid values, pass {AggregatedValues: "%{base}Metrics"}. See SchemaElements::TypeNamer::DEFAULT_FORMATS
+for the available formats.
overrides for the names of specific enum values for
+specific enum types. For example, to rename the DayOfWeek.MONDAY enum to DayOfWeek.MON, pass {DayOfWeek: {MONDAY: "MON"}}.
List of Ruby modules to extend onto the SchemaDefinition::API instance. Designed to
+support ElasticGraph extension gems (such as elasticgraph-apollo).
Whether or not to enforce the requirement that the JSON schema version is incremented
+every time dumping the JSON schemas results in a changed artifact. Generally speaking, you will want this to be true for any
+ElasticGraph application that is in production as the versioning of JSON schemas is what supports safe schema evolution as it
+allows ElasticGraph to identify which version of the JSON schema the publishing system was operating on when it published an
+event. It can be useful to set it to false before your application is in production, as you do not want to be forced to bump
+the version after every single schema change while you are building an initial prototype.
Returns the JSON schema for the requested version, if available.
+
+
+
+
+
+
Parameters:
+
+
+
+
+ version
+
+
+ (Integer)
+
+
+
+ —
+
desired JSON schema version
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Hash<String, Object>)
+
+
+
+ —
+
the JSON schema for the requested version, if available
+
+
+
+
+
+
Raises:
+
+
+
+
+
+ (Errors::NotFoundError)
+
+
+
+ —
+
if the requested JSON schema version is not available
+
+
+
+
+
+
+
+
+
+
+
+
+51
+52
+53
+54
+55
+56
+57
+
+
+
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/results.rb', line 51
+
+defjson_schemas_for(version)
+ unlessavailable_json_schema_versions.include?(version)
+ raiseErrors::NotFoundError,"The requested json schema version (#{version}) is not available. Available versions: #{available_json_schema_versions.to_a.join(", ")}."
+ end
+
+ @latest_versioned_json_schema||=merge_field_metadata_into_json_schema(current_public_json_schema).json_schema
+end
When the argument type is an enum, and we’re configured with different naming for input vs output enums, we need to convert the value type to its input form.
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/schema_elements/argument.rb', line 30
+
+classArgument<Struct.new(:schema_def_state,:parent_field,:name,:original_value_type)
+ prependMixins::VerifiesGraphQLName
+ prependMixins::SupportsDefaultValue
+ includeMixins::HasDocumentation
+ includeMixins::HasDirectives
+ includeMixins::HasReadableToSAndInspect.new{|a|"#{a.parent_field.parent_type.name}.#{a.parent_field.name}(#{a.name}: #{a.value_type})"}
+
+ # @return [String] GraphQL SDL form of the argument
+defto_sdl
+ "#{formatted_documentation}#{name}: #{value_type}#{default_value_sdl}#{directives_sdl(prefix_with:"")}"
+ end
+
+ # When the argument type is an enum, and we're configured with different naming for input vs output enums,
+# we need to convert the value type to its input form. Note that this intentionally happens lazily (rather than
+# doing this when `Argument` is instantiated), because the referenced type need not exist when the argument
+# is defined, and we may not be able to figure out if it's an enum until the type has been defined. So, we
+# apply this lazily.
+#
+# @return [TypeReference] the type of the argument
+# @see #original_value_type
+defvalue_type
+ original_value_type.to_final_form(as_input:true)
+ end
+end
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/schema_elements/argument.rb', line 30
+
+classArgument<Struct.new(:schema_def_state,:parent_field,:name,:original_value_type)
+ prependMixins::VerifiesGraphQLName
+ prependMixins::SupportsDefaultValue
+ includeMixins::HasDocumentation
+ includeMixins::HasDirectives
+ includeMixins::HasReadableToSAndInspect.new{|a|"#{a.parent_field.parent_type.name}.#{a.parent_field.name}(#{a.name}: #{a.value_type})"}
+
+ # @return [String] GraphQL SDL form of the argument
+defto_sdl
+ "#{formatted_documentation}#{name}: #{value_type}#{default_value_sdl}#{directives_sdl(prefix_with:"")}"
+ end
+
+ # When the argument type is an enum, and we're configured with different naming for input vs output enums,
+# we need to convert the value type to its input form. Note that this intentionally happens lazily (rather than
+# doing this when `Argument` is instantiated), because the referenced type need not exist when the argument
+# is defined, and we may not be able to figure out if it's an enum until the type has been defined. So, we
+# apply this lazily.
+#
+# @return [TypeReference] the type of the argument
+# @see #original_value_type
+defvalue_type
+ original_value_type.to_final_form(as_input:true)
+ end
+end
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/schema_elements/argument.rb', line 30
+
+classArgument<Struct.new(:schema_def_state,:parent_field,:name,:original_value_type)
+ prependMixins::VerifiesGraphQLName
+ prependMixins::SupportsDefaultValue
+ includeMixins::HasDocumentation
+ includeMixins::HasDirectives
+ includeMixins::HasReadableToSAndInspect.new{|a|"#{a.parent_field.parent_type.name}.#{a.parent_field.name}(#{a.name}: #{a.value_type})"}
+
+ # @return [String] GraphQL SDL form of the argument
+defto_sdl
+ "#{formatted_documentation}#{name}: #{value_type}#{default_value_sdl}#{directives_sdl(prefix_with:"")}"
+ end
+
+ # When the argument type is an enum, and we're configured with different naming for input vs output enums,
+# we need to convert the value type to its input form. Note that this intentionally happens lazily (rather than
+# doing this when `Argument` is instantiated), because the referenced type need not exist when the argument
+# is defined, and we may not be able to figure out if it's an enum until the type has been defined. So, we
+# apply this lazily.
+#
+# @return [TypeReference] the type of the argument
+# @see #original_value_type
+defvalue_type
+ original_value_type.to_final_form(as_input:true)
+ end
+end
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/schema_elements/argument.rb', line 30
+
+classArgument<Struct.new(:schema_def_state,:parent_field,:name,:original_value_type)
+ prependMixins::VerifiesGraphQLName
+ prependMixins::SupportsDefaultValue
+ includeMixins::HasDocumentation
+ includeMixins::HasDirectives
+ includeMixins::HasReadableToSAndInspect.new{|a|"#{a.parent_field.parent_type.name}.#{a.parent_field.name}(#{a.name}: #{a.value_type})"}
+
+ # @return [String] GraphQL SDL form of the argument
+defto_sdl
+ "#{formatted_documentation}#{name}: #{value_type}#{default_value_sdl}#{directives_sdl(prefix_with:"")}"
+ end
+
+ # When the argument type is an enum, and we're configured with different naming for input vs output enums,
+# we need to convert the value type to its input form. Note that this intentionally happens lazily (rather than
+# doing this when `Argument` is instantiated), because the referenced type need not exist when the argument
+# is defined, and we may not be able to figure out if it's an enum until the type has been defined. So, we
+# apply this lazily.
+#
+# @return [TypeReference] the type of the argument
+# @see #original_value_type
+defvalue_type
+ original_value_type.to_final_form(as_input:true)
+ end
+end
When the argument type is an enum, and we’re configured with different naming for input vs output enums,
+we need to convert the value type to its input form. Note that this intentionally happens lazily (rather than
+doing this when Argument is instantiated), because the referenced type need not exist when the argument
+is defined, and we may not be able to figure out if it’s an enum until the type has been defined. So, we
+apply this lazily.
Represents signed double-precision fractional values as specified by
+IEEE 754.
+
ID
+
Represents a unique identifier that is Base64 obfuscated. It is often used to
+refetch an object or as key for a cache. The ID type appears in a JSON response as a
+String; however, it is not intended to be human-readable. When expected as an input
+type, any string (such as "VXNlci0xMA==") or integer (such as 4) input value will
+be accepted as an ID.
+
Int
+
Represents non-fractional signed whole numeric values. Int can represent values between
+-(2^31) and 2^31 - 1.
+
String
+
Represents textual data as UTF-8 character sequences. This type is most often used by
+GraphQL to represent free-form human-readable text.
+
+
+
Additional ElasticGraph Scalars
+
+
ElasticGraph defines these additional scalar types.
+
+
+
Cursor
+
An opaque string value representing a specific location in a paginated connection type.
+Returned cursors can be passed back in the next query via the before or after
+arguments to continue paginating from that point.
A numeric type for large integer values that can serialize safely as JSON. While JSON
+itself has no hard limit on the size of integers, the RFC-7159 spec mentions that
+values outside of the range -9,007,199,254,740,991 (-(2^53) + 1) to 9,007,199,254,740,991
+(2^53 - 1) may not be interopable with all JSON implementations. As it turns out, the
+number implementation used by JavaScript has this issue. When you parse a JSON string that
+contains a numeric value like 4693522397653681111, the parsed result will contain a
+rounded value like 4693522397653681000. While this is entirely a client-side problem,
+we want to preserve maximum compatibility with common client languages. Given the ubiquity
+of GraphiQL as a GraphQL client, we want to avoid this problem. Our solution is to support
+two separate types:
+
+
+
This type (JsonSafeLong) is serialized as a number, but limits values to the safely
+serializable range.
+
The LongString type supports long values that use all 64 bits, but serializes as a
+string rather than a number, avoiding the JavaScript compatibility problems. For more
+background, see the JavaScript Number.MAX_SAFE_INTEGER
+docs.
+
+
+
LocalTime
+
A local time such as "23:59:33" or "07:20:47.454" without a time zone or offset,
+formatted based on the partial-time portion of
+RFC3339.
+
LongString
+
A numeric type for large integer values in the inclusive range -2^63 (-9,223,372,036,854,775,808)
+to (2^63 - 1) (9,223,372,036,854,775,807). Note that LongString values are serialized as strings
+within JSON, to avoid interopability problems with JavaScript. If you want a large integer type
+that serializes within JSON as a number, use JsonSafeLong.
A custom scalar type that allows any type of data, including:
+
+
+
strings
+
numbers
+
objects and arrays (nested as deeply as you like)
+
booleans
+
+
+
Note: fields of this type are effectively untyped. We recommend it only be used for parts
+of your schema that can’t be statically typed.
+
+
+
+
Enum Types
+
+
ElasticGraph defines these enum types. Most of these are intended for usage as an input
+argument, but they could be used as a return type in your schema if they meet your needs.
+
+
+
DateGroupingGranularity
+
Enumerates the supported granularities of a Date.
+
DateGroupingTruncationUnit
+
Enumerates the supported truncation units of a Date.
+
DateTimeGroupingGranularity
+
Enumerates the supported granularities of a DateTime.
+
DateTimeGroupingTruncationUnit
+
Enumerates the supported truncation units of a DateTime.
+
DateTimeUnit
+
Enumeration of DateTime units.
+
DateUnit
+
Enumeration of Date units.
+
DayOfWeek
+
Indicates the specific day of the week.
+
DistanceUnit
+
Enumerates the supported distance units.
+
LocalTimeGroupingTruncationUnit
+
Enumerates the supported truncation units of a LocalTime.
+
LocalTimeUnit
+
Enumeration of LocalTime units.
+
MatchesQueryAllowedEditsPerTerm
+
Enumeration of allowed values for the matchesQuery: {allowedEditsPerTerm: ...} filter option.
+
+
+
Object Types
+
+
ElasticGraph defines these object types.
+
+
+
AggregationCountDetail
+
Provides detail about an aggregation count.
+
GeoLocation
+
Geographic coordinates representing a location on the Earth’s surface.
Defines a GraphQL enum type.
+The type is restricted to an enumerated set of values, each with a unique name.
+Use value or values to define the enum values in the passed block.
+
+
Note: if required by your configuration, this may generate a pair of Enum types (an input
+enum and an output enum).
+
+
+
+
+
+
+
+
Examples:
+
+
+
Define an enum type
+
+
+
ElasticGraph.define_schemado|schema|
+ schema.enum_type"Currency"do|t|
+ # in the block, `t` is an EnumType
+t.value"USD"
+ end
+end
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/schema_elements/enum_type.rb', line 39
+
+classEnumType<Struct.new(:schema_def_state,:type_ref,:for_output,:values_by_name)
+ # @dynamic type_ref, graphql_only?
+prependMixins::VerifiesGraphQLName
+ includeMixins::CanBeGraphQLOnly
+ includeMixins::HasDocumentation
+ includeMixins::HasDirectives
+ includeMixins::HasDerivedGraphQLTypeCustomizations
+ includeMixins::HasReadableToSAndInspect.new{|e|e.name}
+
+ # @private
+definitialize(schema_def_state,name)
+ # @type var values_by_name: ::Hash[::String, EnumValue]
+values_by_name={}
+ super(schema_def_state,schema_def_state.type_ref(name).to_final_form,true,values_by_name)
+
+ # :nocov: -- currently all invocations have a block
+yieldselfifblock_given?
+ # :nocov:
+end
+
+ # @return [String] name of the enum type
+defname
+ type_ref.name
+ end
+
+ # @return [TypeReference] reference to `AggregatedValues` type to use for this enum.
+defaggregated_values_type
+ schema_def_state.type_ref("NonNumeric").as_aggregated_values
+ end
+
+ # Defines an enum value for the current enum type.
+#
+# @param value_name [String] name of the enum value
+# @yield [EnumValue] enum value so it can be further customized
+# @return [void]
+#
+# @example Define an enum type with multiple enum values
+# ElasticGraph.define_schema do |schema|
+# schema.enum_type "Currency" do |t|
+# t.value "USD" do |v|
+# v.documentation "US Dollars."
+# end
+#
+# t.value "JPY" do |v|
+# v.documentation "Japanese Yen."
+# end
+# end
+# end
+defvalue(value_name,&block)
+ alternate_original_name=value_name
+ value_name=schema_def_state.enum_value_namer.name_for(name,value_name.to_s)
+
+ ifvalues_by_name.key?(value_name)
+ raiseErrors::SchemaError,"Duplicate value on Enum::Type #{name}: #{value_name}"
+ end
+
+ ifvalue_name.length>DEFAULT_MAX_KEYWORD_LENGTH
+ raiseErrors::SchemaError,"Enum value `#{name}.#{value_name}` is too long: it is #{value_name.length} characters but cannot exceed #{DEFAULT_MAX_KEYWORD_LENGTH} characters."
+ end
+
+ values_by_name[value_name]=schema_def_state.factory.new_enum_value(value_name,alternate_original_name,&block)
+ end
+
+ # Defines multiple enum values. In contrast to {#value}, the enum values cannot be customized
+# further via a block.
+#
+# @param value_names [Array<String>] names of the enum values
+# @return [void]
+#
+# @example Define an enum type with multiple enum values
+# ElasticGraph.define_schema do |schema|
+# schema.enum_type "Currency" do |t|
+# t.values "USD", "JPY", "CAD", "GBP"
+# end
+# end
+defvalues(*value_names)
+ value_names.flatten.each{|name|value(name)}
+ end
+
+ # @return [SchemaArtifacts::RuntimeMetadata::Enum::Type] runtime metadata for this enum type
+defruntime_metadata
+ runtime_metadata_values_by_name=values_by_name
+ .transform_values(&:runtime_metadata)
+ .compact
+
+ SchemaArtifacts::RuntimeMetadata::Enum::Type.new(values_by_name:runtime_metadata_values_by_name)
+ end
+
+ # @return [String] GraphQL SDL form of the enum type
+defto_sdl
+ ifvalues_by_name.empty?
+ raiseErrors::SchemaError,"Enum type #{name} has no values, but enums must have at least one value."
+ end
+
+ <<~EOS
+#{formatted_documentation}enum #{name}#{directives_sdl(suffix_with:"")}{
+#{values_by_name.values.map(&:to_sdl).flat_map{|s|s.split("\n")}.join("\n ")}
+ }
+ EOS
+end
+
+ # @private
+defderived_graphql_types
+ # Derived GraphQL types must be generated for an output enum. For an enum type that is only
+# used as an input, we do not need derived types.
+return[]unlessfor_output
+
+ derived_scalar_types=schema_def_state.factory.new_scalar_type(name)do|t|
+ t.mappingtype:"keyword"
+ t.json_schematype:"string"
+ t.graphql_onlygraphql_only?
+ end.derived_graphql_types
+
+ if(input_enum=as_input).equal?(self)
+ derived_scalar_types
+ else
+ [input_enum]+derived_scalar_types
+ end
+ end
+
+ # @return [Indexing::FieldType::Enum] indexing representation of this enum type
+defto_indexing_field_type
+ Indexing::FieldType::Enum.new(values_by_name.keys)
+ end
+
+ # @return [false] enum types are never directly indexed
+defindexed?
+ false
+ end
+
+ # @return [EnumType] converts the enum type to its input form for when different naming is used for input vs output enums.
+defas_input
+ input_name=type_ref
+ .as_input_enum# To apply the configured format for input enums.
+.to_final_form# To handle a type name override of the input enum.
+.name
+
+ returnselfifinput_name==name
+
+ schema_def_state.factory.new_enum_type(input_name)do|t|
+ t.for_output=false# flag that it's not used as an output enum, and therefore `derived_graphql_types` will be empty on it.
+t.graphql_onlytrue# input enums are always GraphQL-only.
+t.documentationdoc_comment
+ directives.each{|dir|dir.duplicate_on(t)}
+ values_by_name.each{|_,val|val.duplicate_on(t)}
+ end
+ end
+end
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/schema_elements/enum_type.rb', line 39
+
+classEnumType<Struct.new(:schema_def_state,:type_ref,:for_output,:values_by_name)
+ # @dynamic type_ref, graphql_only?
+prependMixins::VerifiesGraphQLName
+ includeMixins::CanBeGraphQLOnly
+ includeMixins::HasDocumentation
+ includeMixins::HasDirectives
+ includeMixins::HasDerivedGraphQLTypeCustomizations
+ includeMixins::HasReadableToSAndInspect.new{|e|e.name}
+
+ # @private
+definitialize(schema_def_state,name)
+ # @type var values_by_name: ::Hash[::String, EnumValue]
+values_by_name={}
+ super(schema_def_state,schema_def_state.type_ref(name).to_final_form,true,values_by_name)
+
+ # :nocov: -- currently all invocations have a block
+yieldselfifblock_given?
+ # :nocov:
+end
+
+ # @return [String] name of the enum type
+defname
+ type_ref.name
+ end
+
+ # @return [TypeReference] reference to `AggregatedValues` type to use for this enum.
+defaggregated_values_type
+ schema_def_state.type_ref("NonNumeric").as_aggregated_values
+ end
+
+ # Defines an enum value for the current enum type.
+#
+# @param value_name [String] name of the enum value
+# @yield [EnumValue] enum value so it can be further customized
+# @return [void]
+#
+# @example Define an enum type with multiple enum values
+# ElasticGraph.define_schema do |schema|
+# schema.enum_type "Currency" do |t|
+# t.value "USD" do |v|
+# v.documentation "US Dollars."
+# end
+#
+# t.value "JPY" do |v|
+# v.documentation "Japanese Yen."
+# end
+# end
+# end
+defvalue(value_name,&block)
+ alternate_original_name=value_name
+ value_name=schema_def_state.enum_value_namer.name_for(name,value_name.to_s)
+
+ ifvalues_by_name.key?(value_name)
+ raiseErrors::SchemaError,"Duplicate value on Enum::Type #{name}: #{value_name}"
+ end
+
+ ifvalue_name.length>DEFAULT_MAX_KEYWORD_LENGTH
+ raiseErrors::SchemaError,"Enum value `#{name}.#{value_name}` is too long: it is #{value_name.length} characters but cannot exceed #{DEFAULT_MAX_KEYWORD_LENGTH} characters."
+ end
+
+ values_by_name[value_name]=schema_def_state.factory.new_enum_value(value_name,alternate_original_name,&block)
+ end
+
+ # Defines multiple enum values. In contrast to {#value}, the enum values cannot be customized
+# further via a block.
+#
+# @param value_names [Array<String>] names of the enum values
+# @return [void]
+#
+# @example Define an enum type with multiple enum values
+# ElasticGraph.define_schema do |schema|
+# schema.enum_type "Currency" do |t|
+# t.values "USD", "JPY", "CAD", "GBP"
+# end
+# end
+defvalues(*value_names)
+ value_names.flatten.each{|name|value(name)}
+ end
+
+ # @return [SchemaArtifacts::RuntimeMetadata::Enum::Type] runtime metadata for this enum type
+defruntime_metadata
+ runtime_metadata_values_by_name=values_by_name
+ .transform_values(&:runtime_metadata)
+ .compact
+
+ SchemaArtifacts::RuntimeMetadata::Enum::Type.new(values_by_name:runtime_metadata_values_by_name)
+ end
+
+ # @return [String] GraphQL SDL form of the enum type
+defto_sdl
+ ifvalues_by_name.empty?
+ raiseErrors::SchemaError,"Enum type #{name} has no values, but enums must have at least one value."
+ end
+
+ <<~EOS
+#{formatted_documentation}enum #{name}#{directives_sdl(suffix_with:"")}{
+#{values_by_name.values.map(&:to_sdl).flat_map{|s|s.split("\n")}.join("\n ")}
+ }
+ EOS
+end
+
+ # @private
+defderived_graphql_types
+ # Derived GraphQL types must be generated for an output enum. For an enum type that is only
+# used as an input, we do not need derived types.
+return[]unlessfor_output
+
+ derived_scalar_types=schema_def_state.factory.new_scalar_type(name)do|t|
+ t.mappingtype:"keyword"
+ t.json_schematype:"string"
+ t.graphql_onlygraphql_only?
+ end.derived_graphql_types
+
+ if(input_enum=as_input).equal?(self)
+ derived_scalar_types
+ else
+ [input_enum]+derived_scalar_types
+ end
+ end
+
+ # @return [Indexing::FieldType::Enum] indexing representation of this enum type
+defto_indexing_field_type
+ Indexing::FieldType::Enum.new(values_by_name.keys)
+ end
+
+ # @return [false] enum types are never directly indexed
+defindexed?
+ false
+ end
+
+ # @return [EnumType] converts the enum type to its input form for when different naming is used for input vs output enums.
+defas_input
+ input_name=type_ref
+ .as_input_enum# To apply the configured format for input enums.
+.to_final_form# To handle a type name override of the input enum.
+.name
+
+ returnselfifinput_name==name
+
+ schema_def_state.factory.new_enum_type(input_name)do|t|
+ t.for_output=false# flag that it's not used as an output enum, and therefore `derived_graphql_types` will be empty on it.
+t.graphql_onlytrue# input enums are always GraphQL-only.
+t.documentationdoc_comment
+ directives.each{|dir|dir.duplicate_on(t)}
+ values_by_name.each{|_,val|val.duplicate_on(t)}
+ end
+ end
+end
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/schema_elements/enum_type.rb', line 39
+
+classEnumType<Struct.new(:schema_def_state,:type_ref,:for_output,:values_by_name)
+ # @dynamic type_ref, graphql_only?
+prependMixins::VerifiesGraphQLName
+ includeMixins::CanBeGraphQLOnly
+ includeMixins::HasDocumentation
+ includeMixins::HasDirectives
+ includeMixins::HasDerivedGraphQLTypeCustomizations
+ includeMixins::HasReadableToSAndInspect.new{|e|e.name}
+
+ # @private
+definitialize(schema_def_state,name)
+ # @type var values_by_name: ::Hash[::String, EnumValue]
+values_by_name={}
+ super(schema_def_state,schema_def_state.type_ref(name).to_final_form,true,values_by_name)
+
+ # :nocov: -- currently all invocations have a block
+yieldselfifblock_given?
+ # :nocov:
+end
+
+ # @return [String] name of the enum type
+defname
+ type_ref.name
+ end
+
+ # @return [TypeReference] reference to `AggregatedValues` type to use for this enum.
+defaggregated_values_type
+ schema_def_state.type_ref("NonNumeric").as_aggregated_values
+ end
+
+ # Defines an enum value for the current enum type.
+#
+# @param value_name [String] name of the enum value
+# @yield [EnumValue] enum value so it can be further customized
+# @return [void]
+#
+# @example Define an enum type with multiple enum values
+# ElasticGraph.define_schema do |schema|
+# schema.enum_type "Currency" do |t|
+# t.value "USD" do |v|
+# v.documentation "US Dollars."
+# end
+#
+# t.value "JPY" do |v|
+# v.documentation "Japanese Yen."
+# end
+# end
+# end
+defvalue(value_name,&block)
+ alternate_original_name=value_name
+ value_name=schema_def_state.enum_value_namer.name_for(name,value_name.to_s)
+
+ ifvalues_by_name.key?(value_name)
+ raiseErrors::SchemaError,"Duplicate value on Enum::Type #{name}: #{value_name}"
+ end
+
+ ifvalue_name.length>DEFAULT_MAX_KEYWORD_LENGTH
+ raiseErrors::SchemaError,"Enum value `#{name}.#{value_name}` is too long: it is #{value_name.length} characters but cannot exceed #{DEFAULT_MAX_KEYWORD_LENGTH} characters."
+ end
+
+ values_by_name[value_name]=schema_def_state.factory.new_enum_value(value_name,alternate_original_name,&block)
+ end
+
+ # Defines multiple enum values. In contrast to {#value}, the enum values cannot be customized
+# further via a block.
+#
+# @param value_names [Array<String>] names of the enum values
+# @return [void]
+#
+# @example Define an enum type with multiple enum values
+# ElasticGraph.define_schema do |schema|
+# schema.enum_type "Currency" do |t|
+# t.values "USD", "JPY", "CAD", "GBP"
+# end
+# end
+defvalues(*value_names)
+ value_names.flatten.each{|name|value(name)}
+ end
+
+ # @return [SchemaArtifacts::RuntimeMetadata::Enum::Type] runtime metadata for this enum type
+defruntime_metadata
+ runtime_metadata_values_by_name=values_by_name
+ .transform_values(&:runtime_metadata)
+ .compact
+
+ SchemaArtifacts::RuntimeMetadata::Enum::Type.new(values_by_name:runtime_metadata_values_by_name)
+ end
+
+ # @return [String] GraphQL SDL form of the enum type
+defto_sdl
+ ifvalues_by_name.empty?
+ raiseErrors::SchemaError,"Enum type #{name} has no values, but enums must have at least one value."
+ end
+
+ <<~EOS
+#{formatted_documentation}enum #{name}#{directives_sdl(suffix_with:"")}{
+#{values_by_name.values.map(&:to_sdl).flat_map{|s|s.split("\n")}.join("\n ")}
+ }
+ EOS
+end
+
+ # @private
+defderived_graphql_types
+ # Derived GraphQL types must be generated for an output enum. For an enum type that is only
+# used as an input, we do not need derived types.
+return[]unlessfor_output
+
+ derived_scalar_types=schema_def_state.factory.new_scalar_type(name)do|t|
+ t.mappingtype:"keyword"
+ t.json_schematype:"string"
+ t.graphql_onlygraphql_only?
+ end.derived_graphql_types
+
+ if(input_enum=as_input).equal?(self)
+ derived_scalar_types
+ else
+ [input_enum]+derived_scalar_types
+ end
+ end
+
+ # @return [Indexing::FieldType::Enum] indexing representation of this enum type
+defto_indexing_field_type
+ Indexing::FieldType::Enum.new(values_by_name.keys)
+ end
+
+ # @return [false] enum types are never directly indexed
+defindexed?
+ false
+ end
+
+ # @return [EnumType] converts the enum type to its input form for when different naming is used for input vs output enums.
+defas_input
+ input_name=type_ref
+ .as_input_enum# To apply the configured format for input enums.
+.to_final_form# To handle a type name override of the input enum.
+.name
+
+ returnselfifinput_name==name
+
+ schema_def_state.factory.new_enum_type(input_name)do|t|
+ t.for_output=false# flag that it's not used as an output enum, and therefore `derived_graphql_types` will be empty on it.
+t.graphql_onlytrue# input enums are always GraphQL-only.
+t.documentationdoc_comment
+ directives.each{|dir|dir.duplicate_on(t)}
+ values_by_name.each{|_,val|val.duplicate_on(t)}
+ end
+ end
+end
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/schema_elements/enum_type.rb', line 170
+
+defas_input
+ input_name=type_ref
+ .as_input_enum# To apply the configured format for input enums.
+.to_final_form# To handle a type name override of the input enum.
+.name
+
+ returnselfifinput_name==name
+
+ schema_def_state.factory.new_enum_type(input_name)do|t|
+ t.for_output=false# flag that it's not used as an output enum, and therefore `derived_graphql_types` will be empty on it.
+t.graphql_onlytrue# input enums are always GraphQL-only.
+t.documentationdoc_comment
+ directives.each{|dir|dir.duplicate_on(t)}
+ values_by_name.each{|_,val|val.duplicate_on(t)}
+ end
+end
+
+
+
+
+
+
+
+
+ #indexed? ⇒ false
+
+
+
+
+
+
+
+
Returns enum types are never directly indexed.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (false)
+
+
+
+ —
+
enum types are never directly indexed
+
+
+
+
+
+
+
+
+
+
+
+
+165
+166
+167
+
+
+
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/schema_elements/enum_type.rb', line 165
+
+defindexed?
+ false
+end
+
+
+
+
+
+
+
+
+ #name ⇒ String
+
+
+
+
+
+
+
+
Returns name of the enum type.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String)
+
+
+
+ —
+
name of the enum type
+
+
+
+
+
+
+
+
+
+
+
+
+60
+61
+62
+
+
+
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/schema_elements/enum_type.rb', line 60
+
+defname
+ type_ref.name
+end
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/schema_elements/enum_type.rb', line 128
+
+defto_sdl
+ ifvalues_by_name.empty?
+ raiseErrors::SchemaError,"Enum type #{name} has no values, but enums must have at least one value."
+ end
+
+ <<~EOS
+#{formatted_documentation}enum #{name}#{directives_sdl(suffix_with:"")}{
+#{values_by_name.values.map(&:to_sdl).flat_map{|s|s.split("\n")}.join("\n ")}
+ }
+ EOS
+end
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/schema_elements/enum_type.rb', line 87
+
+defvalue(value_name,&block)
+ alternate_original_name=value_name
+ value_name=schema_def_state.enum_value_namer.name_for(name,value_name.to_s)
+
+ ifvalues_by_name.key?(value_name)
+ raiseErrors::SchemaError,"Duplicate value on Enum::Type #{name}: #{value_name}"
+ end
+
+ ifvalue_name.length>DEFAULT_MAX_KEYWORD_LENGTH
+ raiseErrors::SchemaError,"Enum value `#{name}.#{value_name}` is too long: it is #{value_name.length} characters but cannot exceed #{DEFAULT_MAX_KEYWORD_LENGTH} characters."
+ end
+
+ values_by_name[value_name]=schema_def_state.factory.new_enum_value(value_name,alternate_original_name,&block)
+end
+
+
+
+
+
+
+
+
+ #values(*value_names) ⇒ void
+
+
+
+
+
+
+
+
This method returns an undefined value.
Defines multiple enum values. In contrast to #value, the enum values cannot be customized
+further via a block.
+
+
+
+
+
+
+
+
Examples:
+
+
+
Define an enum type with multiple enum values
+
+
+
ElasticGraph.define_schemado|schema|
+ schema.enum_type"Currency"do|t|
+ t.values"USD","JPY","CAD","GBP"
+ end
+end
+
+
+
Parameters:
+
+
+
+
+ value_names
+
+
+ (Array<String>)
+
+
+
+ —
+
names of the enum values
+
+
+
+
+
+
+
+
+
+
+
+
+
+114
+115
+116
+
+
+
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/schema_elements/enum_type.rb', line 114
+
+defvalues(*value_names)
+ value_names.flatten.each{|name|value(name)}
+end
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/main/ElasticGraph/SchemaDefinition/SchemaElements/EnumValue.html b/docs/main/ElasticGraph/SchemaDefinition/SchemaElements/EnumValue.html
new file mode 100644
index 00000000..34115c50
--- /dev/null
+++ b/docs/main/ElasticGraph/SchemaDefinition/SchemaElements/EnumValue.html
@@ -0,0 +1,979 @@
+
+
+
+
+
+
+ Class: ElasticGraph::SchemaDefinition::SchemaElements::EnumValue
+
+ — Documentation by YARD 0.9.37
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Registers a customization callback that will be applied to the corresponding enum values that will be generated for this field on the derived SortOrder enum type.
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/schema_elements/field.rb', line 89
+
+classField<Struct.new(
+ :name,:original_type,:parent_type,:original_type_for_derived_types,:schema_def_state,:accuracy_confidence,
+ :filter_customizations,:grouped_by_customizations,:sub_aggregations_customizations,
+ :aggregated_values_customizations,:sort_order_enum_value_customizations,
+ :args,:sortable,:filterable,:aggregatable,:groupable,:graphql_only,:source,:runtime_field_script,:relationship,:singular_name,
+ :computation_detail,:non_nullable_in_json_schema,:backing_indexing_field,:as_input,
+ :legacy_grouping_schema,:name_in_index
+)
+ includeMixins::HasDocumentation
+ includeMixins::HasDirectives
+ includeMixins::HasTypeInfo
+ includeMixins::HasReadableToSAndInspect.new{|f|"#{f.parent_type.name}.#{f.name}: #{f.type}"}
+
+ # @private
+definitialize(
+ name:,type:,parent_type:,schema_def_state:,
+ accuracy_confidence::high,name_in_index:name,
+ runtime_metadata_graphql_field:SchemaArtifacts::RuntimeMetadata::GraphQLField::EMPTY,
+ type_for_derived_types:nil,graphql_only:nil,singular:nil,
+ sortable:nil,filterable:nil,aggregatable:nil,groupable:nil,
+ backing_indexing_field:nil,as_input:false,legacy_grouping_schema:false
+ )
+ type_ref=schema_def_state.type_ref(type)
+ super(
+ name:name,
+ original_type:type_ref,
+ parent_type:parent_type,
+ original_type_for_derived_types:type_for_derived_types?schema_def_state.type_ref(type_for_derived_types):type_ref,
+ schema_def_state:schema_def_state,
+ accuracy_confidence:accuracy_confidence,
+ filter_customizations:[],
+ grouped_by_customizations:[],
+ sub_aggregations_customizations:[],
+ aggregated_values_customizations:[],
+ sort_order_enum_value_customizations:[],
+ args:{},
+ sortable:sortable,
+ filterable:filterable,
+ aggregatable:aggregatable,
+ groupable:groupable,
+ graphql_only:graphql_only,
+ source:nil,
+ runtime_field_script:nil,
+ # Note: we named the keyword argument `singular` (with no `_name` suffix) for consistency with
+# other schema definition APIs, which also use `singular:` instead of `singular_name:`. We include
+# the `_name` suffix on the attribute for clarity.
+singular_name:singular,
+ name_in_index:name_in_index,
+ non_nullable_in_json_schema:false,
+ backing_indexing_field:backing_indexing_field,
+ as_input:as_input,
+ legacy_grouping_schema:legacy_grouping_schema
+ )
+
+ ifname!=name_in_index&&name_in_index&.include?(".")&&!graphql_only
+ raiseErrors::SchemaError,"#{self} has an invalid `name_in_index`: #{name_in_index.inspect}. Only `graphql_only: true` fields can have a `name_in_index` that references a child field."
+ end
+
+ schema_def_state.register_user_defined_field(self)
+ yieldselfifblock_given?
+ end
+
+ # @private
+@@initialize_param_names=instance_method(:initialize).parameters.map(&:last).to_set
+
+ # must come after we capture the initialize params.
+prependMixins::VerifiesGraphQLName
+
+ # @return [TypeReference] the type of this field
+deftype
+ # Here we lazily convert the `original_type` to an input type as needed. This must be lazy because
+# the logic of `as_input` depends on detecting whether the type is an enum type, which it may not
+# be able to do right away--we assume not if we can't tell, and retry every time this method is called.
+original_type.to_final_form(as_input:as_input)
+ end
+
+ # @return [TypeReference] the type of the corresponding field on derived types (usually this is the same as {#type}).
+#
+# @private
+deftype_for_derived_types
+ original_type_for_derived_types.to_final_form(as_input:as_input)
+ end
+
+ # @note For each field defined in your schema that is filterable, a corresponding filtering field will be created on the
+# `*FilterInput` type derived from the parent object type.
+#
+# Registers a customization callback that will be applied to the corresponding filtering field that will be generated for this
+# field.
+#
+# @yield [Field] derived filtering field
+# @return [void]
+# @see #customize_aggregated_values_field
+# @see #customize_grouped_by_field
+# @see #customize_sort_order_enum_values
+# @see #customize_sub_aggregations_field
+# @see #on_each_generated_schema_element
+#
+# @example Mark `CampaignFilterInput.organizationId` with `@deprecated`
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Campaign" do |t|
+# t.field "id", "ID"
+#
+# t.field "organizationId", "ID" do |f|
+# f.customize_filter_field do |ff|
+# ff.directive "deprecated"
+# end
+# end
+#
+# t.index "campaigns"
+# end
+# end
+defcustomize_filter_field(&customization_block)
+ filter_customizations<<customization_block
+ end
+
+ # @note For each field defined in your schema that is aggregatable, a corresponding `aggregatedValues` field will be created on the
+# `*AggregatedValues` type derived from the parent object type.
+#
+# Registers a customization callback that will be applied to the corresponding `aggregatedValues` field that will be generated for
+# this field.
+#
+# @yield [Field] derived aggregated values field
+# @return [void]
+# @see #customize_filter_field
+# @see #customize_grouped_by_field
+# @see #customize_sort_order_enum_values
+# @see #customize_sub_aggregations_field
+# @see #on_each_generated_schema_element
+#
+# @example Mark `CampaignAggregatedValues.adImpressions` with `@deprecated`
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Campaign" do |t|
+# t.field "id", "ID"
+#
+# t.field "adImpressions", "Int" do |f|
+# f.customize_aggregated_values_field do |avf|
+# avf.directive "deprecated"
+# end
+# end
+#
+# t.index "campaigns"
+# end
+# end
+defcustomize_aggregated_values_field(&customization_block)
+ aggregated_values_customizations<<customization_block
+ end
+
+ # @note For each field defined in your schema that is groupable, a corresponding `groupedBy` field will be created on the
+# `*AggregationGroupedBy` type derived from the parent object type.
+#
+# Registers a customization callback that will be applied to the corresponding `groupedBy` field that will be generated for this
+# field.
+#
+# @yield [Field] derived grouped by field
+# @return [void]
+# @see #customize_aggregated_values_field
+# @see #customize_filter_field
+# @see #customize_sort_order_enum_values
+# @see #customize_sub_aggregations_field
+# @see #on_each_generated_schema_element
+#
+# @example Mark `CampaignGroupedBy.organizationId` with `@deprecated`
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Campaign" do |t|
+# t.field "id", "ID"
+#
+# t.field "organizationId", "ID" do |f|
+# f.customize_grouped_by_field do |gbf|
+# gbf.directive "deprecated"
+# end
+# end
+#
+# t.index "campaigns"
+# end
+# end
+defcustomize_grouped_by_field(&customization_block)
+ grouped_by_customizations<<customization_block
+ end
+
+ # @note For each field defined in your schema that is sub-aggregatable (e.g. list fields indexed using the `nested` mapping type),
+# a corresponding field will be created on the `*AggregationSubAggregations` type derived from the parent object type.
+#
+# Registers a customization callback that will be applied to the corresponding `subAggregations` field that will be generated for
+# this field.
+#
+# @yield [Field] derived sub-aggregations field
+# @return [void]
+# @see #customize_aggregated_values_field
+# @see #customize_filter_field
+# @see #customize_grouped_by_field
+# @see #customize_sort_order_enum_values
+# @see #on_each_generated_schema_element
+#
+# @example Mark `TransactionAggregationSubAggregations.fees` with `@deprecated`
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Transaction" do |t|
+# t.field "id", "ID"
+#
+# t.field "fees", "[Money!]!" do |f|
+# f.mapping type: "nested"
+#
+# f.customize_sub_aggregations_field do |saf|
+# # Adds a `@deprecated` directive to the `PaymentAggregationSubAggregations.fees`
+# # field without also adding it to the `Payment.fees` field.
+# saf.directive "deprecated"
+# end
+# end
+#
+# t.index "transactions"
+# end
+#
+# schema.object_type "Money" do |t|
+# t.field "amount", "Int"
+# t.field "currency", "String"
+# end
+# end
+defcustomize_sub_aggregations_field(&customization_block)
+ sub_aggregations_customizations<<customization_block
+ end
+
+ # @note for each sortable field, enum values will be generated on the derived sort order enum type allowing you to
+# sort by the field `ASC` or `DESC`.
+#
+# Registers a customization callback that will be applied to the corresponding enum values that will be generated for this field
+# on the derived `SortOrder` enum type.
+#
+# @yield [SortOrderEnumValue] derived sort order enum value
+# @return [void]
+# @see #customize_aggregated_values_field
+# @see #customize_filter_field
+# @see #customize_grouped_by_field
+# @see #customize_sub_aggregations_field
+# @see #on_each_generated_schema_element
+#
+# @example Mark `CampaignSortOrder.organizationId_(ASC|DESC)` with `@deprecated`
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Campaign" do |t|
+# t.field "id", "ID"
+#
+# t.field "organizationId", "ID" do |f|
+# f.customize_sort_order_enum_values do |soev|
+# soev.directive "deprecated"
+# end
+# end
+#
+# t.index "campaigns"
+# end
+# end
+defcustomize_sort_order_enum_values(&customization_block)
+ sort_order_enum_value_customizations<<customization_block
+ end
+
+ # When you define a {Field} on an {ObjectType} or {InterfaceType}, ElasticGraph generates up to 6 different GraphQL schema elements
+# for it:
+#
+# * A {Field} is generated on the parent {ObjectType} or {InterfaceType} (that is, this field itself). This is used by clients to
+# ask for values for the field in a response.
+# * A {Field} may be generated on the `*FilterInput` {InputType} derived from the parent {ObjectType} or {InterfaceType}. This is
+# used by clients to specify how the query should filter.
+# * A {Field} may be generated on the `*AggregationGroupedBy` {ObjectType} derived from the parent {ObjectType} or {InterfaceType}.
+# This is used by clients to specify how aggregations should be grouped.
+# * A {Field} may be generated on the `*AggregatedValues` {ObjectType} derived from the parent {ObjectType} or {InterfaceType}.
+# This is used by clients to apply aggregation functions (e.g. `sum`, `max`, `min`, etc) to a set of field values for a group.
+# * A {Field} may be generated on the `*AggregationSubAggregations` {ObjectType} derived from the parent {ObjectType} or
+# {InterfaceType}. This is used by clients to perform sub-aggregations on list fields indexed using the `nested` mapping type.
+# * Multiple {EnumValue}s (both `*_ASC` and `*_DESC`) are generated on the `*SortOrder` {EnumType} derived from the parent indexed
+# {ObjectType}. This is used by clients to sort by a field.
+#
+# This method registers a customization callback which is applied to every element that is generated for this field.
+#
+# @yield [Field, EnumValue] the schema element
+# @return [void]
+# @see #customize_aggregated_values_field
+# @see #customize_filter_field
+# @see #customize_grouped_by_field
+# @see #customize_sort_order_enum_values
+# @see #customize_sub_aggregations_field
+#
+# @example
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Transaction" do |t|
+# t.field "id", "ID"
+#
+# t.field "amount", "Int" do |f|
+# f.on_each_generated_schema_element do |element|
+# # Adds a `@deprecated` directive to every GraphQL schema element generated for `amount`:
+# #
+# # - The `Transaction.amount` field.
+# # - The `TransactionFilterInput.amount` field.
+# # - The `TransactionAggregationGroupedBy.amount` field.
+# # - The `TransactionAggregatedValues.amount` field.
+# # - The `TransactionSortOrder.amount_ASC` and`TransactionSortOrder.amount_DESC` enum values.
+# element.directive "deprecated"
+# end
+# end
+#
+# t.index "transactions"
+# end
+# end
+defon_each_generated_schema_element(&customization_block)
+ customization_block.call(self)
+ customize_filter_field(&customization_block)
+ customize_aggregated_values_field(&customization_block)
+ customize_grouped_by_field(&customization_block)
+ customize_sub_aggregations_field(&customization_block)
+ customize_sort_order_enum_values(&customization_block)
+ end
+
+ # (see Mixins::HasTypeInfo#json_schema)
+defjson_schema(nullable:nil,**options)
+ ifoptions.key?(:type)
+ raiseErrors::SchemaError,"Cannot override JSON schema type of field `#{name}` with `#{options.fetch(:type)}`"
+ end
+
+ casenullable
+ whentrue
+ raiseErrors::SchemaError,"`nullable: true` is not allowed on a field--just declare the GraphQL field as being nullable (no `!` suffix) instead."
+ whenfalse
+ self.non_nullable_in_json_schema=true
+ end
+
+ super(**options)
+ end
+
+ # Configures ElasticGraph to source a field’s value from a related object. This can be used to denormalize data at ingestion time to
+# support filtering, grouping, sorting, or aggregating data on a field from a related object.
+#
+# @param relationship [String] name of a relationship defined with {TypeWithSubfields#relates_to_one} using an inbound foreign key
+# which contains the the field you wish to source values from
+# @param field_path [String] dot-separated path to the field on the related type containing values that should be copied to this
+# field
+# @return [void]
+#
+# @example Source `City.currency` from `Country.currency`
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Country" do |t|
+# t.field "id", "ID"
+# t.field "name", "String"
+# t.field "currency", "String"
+# t.relates_to_one "capitalCity", "City", via: "capitalCityId", dir: :out
+# t.index "countries"
+# end
+#
+# schema.object_type "City" do |t|
+# t.field "id", "ID"
+# t.field "name", "String"
+# t.relates_to_one "capitalOf", "Country", via: "capitalCityId", dir: :in
+#
+# t.field "currency", "String" do |f|
+# f.sourced_from "capitalOf", "currency"
+# end
+#
+# t.index "cities"
+# end
+# end
+defsourced_from(relationship,field_path)
+ self.source=schema_def_state.factory.new_field_source(
+ relationship_name:relationship,
+ field_path:field_path
+ )
+ end
+
+ # @private
+defruntime_script(script)
+ self.runtime_field_script=script
+ end
+
+ # Registers an old name that this field used to have in a prior version of the schema.
+#
+# @note In situations where this API applies, ElasticGraph will give you an error message indicating that you need to use this API
+# or {TypeWithSubfields#deleted_field}. Likewise, when ElasticGraph no longer needs to know about this, it'll give you a warning
+# indicating the call to this method can be removed.
+#
+# @param old_name [String] old name this field used to have in a prior version of the schema
+# @return [void]
+#
+# @example Indicate that `Widget.description` used to be called `Widget.notes`.
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Widget" do |t|
+# t.field "description", "String" do |f|
+# f.renamed_from "notes"
+# end
+# end
+# end
+defrenamed_from(old_name)
+ schema_def_state.register_renamed_field(
+ parent_type.name,
+ from:old_name,
+ to:name,
+ defined_at:caller_locations(1,1).first,# : ::Thread::Backtrace::Location
+defined_via:%(field.renamed_from "#{old_name}")
+ )
+ end
+
+ # @private
+defto_sdl(type_structure_only:false,default_value_sdl:nil,&arg_selector)
+ iftype_structure_only
+ "#{name}#{args_sdl(joiner:", ",&arg_selector)}: #{type.name}"
+ else
+ args_sdl=args_sdl(joiner:"\n ",after_opening_paren:"\n ",&arg_selector)
+ "#{formatted_documentation}#{name}#{args_sdl}: #{type.name}#{default_value_sdl}#{directives_sdl}".strip
+ end
+ end
+
+ # Indicates if this field is sortable. Sortable fields will have corresponding `_ASC` and `_DESC` values generated in the
+# sort order {EnumType} of the parent indexed type.
+#
+# By default, the sortability is inferred by the field type and mapping. For example, list fields are not sortable,
+# and fields mapped as `text` are not sortable either. Fields are sortable in most other cases.
+#
+# The `sortable: true` option can be used to force a field to be sortable.
+#
+# @return [Boolean] true if this field is sortable
+defsortable?
+ returnsortableunlesssortable.nil?
+
+ # List fields are not sortable by default. We'd need to provide the datastore a sort mode option:
+# https://www.elastic.co/guide/en/elasticsearch/reference/current/sort-search-results.html#_sort_mode_option
+returnfalseiftype.list?
+
+ # Boolean fields are not sortable by default.
+# - Boolean: sorting all falses before all trues (or whatever) is not generally interesting.
+returnfalseiftype.unwrap_non_null.boolean?
+
+ # Elasticsearch/OpenSearch do not support sorting text fields:
+# > Text fields are not used for sorting...
+# (from https://www.elastic.co/guide/en/elasticsearch/reference/current/the datastore.html#text)
+returnfalseiftext?
+
+ # If the type uses custom mapping type we don't know how if the datastore can sort by it, so we assume it's not sortable.
+returnfalseiftype.as_object_type&.has_custom_mapping_type?
+
+ # Default every other field to being sortable.
+true
+ end
+
+ # Indicates if this field is filterable. Filterable fields will be available in the GraphQL schema under the `filter` argument.
+#
+# Most fields are filterable, except when:
+#
+# - It's a relation. Relation fields require us to load the related data from another index and can't be filtered on.
+# - The field is an object type that isn't itself filterable (e.g. due to having no filterable fields or whatever).
+# - Explicitly disabled with `filterable: false`.
+#
+# @return [Boolean]
+deffilterable?
+ # Object types that use custom index mappings (as `GeoLocation` does) aren't filterable
+# by default since we can't guess what datastore filtering capabilities they have. We've implemented
+# filtering support for `GeoLocation` fields, though, so we need to explicitly make it fliterable here.
+# TODO: clean this up using an interface instead of checking for `GeoLocation`.
+returntrueiftype.fully_unwrapped.name=="GeoLocation"
+
+ returnfalseifrelationship||type.fully_unwrapped.as_object_type&.does_not_support?(&:filterable?)
+ returntrueiffilterable.nil?
+ filterable
+ end
+
+ # Indicates if this field is groupable. Groupable fields will be available under `groupedBy` for an aggregations query.
+#
+# Groupability is inferred based on the field type and mapping type, or you can use the `groupable: true` option to force it.
+#
+# @return [Boolean]
+defgroupable?
+ # If the groupability of the field was specified explicitly when the field was defined, use the specified value.
+returngroupableunlessgroupable.nil?
+
+ # We don't want the `id` field of an indexed type to be available to group by, because it's the unique primary key
+# and the groupings would each contain one document. It's simpler and more efficient to just query the raw documents
+# instead.
+returnfalseifparent_type.indexed?&&name=="id"
+
+ returnfalseifrelationship||type.fully_unwrapped.as_object_type&.does_not_support?(&:groupable?)
+
+ # We don't support grouping an entire list of values, but we do support grouping on individual values in a list.
+# However, we only do so when a `singular_name` has been provided (so that we know what to call the grouped_by field).
+# The semantics are a little odd (since one document can be duplicated in multiple grouping buckets) so we're ok
+# with not offering it by default--the user has to opt-in by telling us what to call the field in its singular form.
+returnlist_field_groupable_by_single_values?iftype.list?&&type.fully_unwrapped.leaf?
+
+ # Nested fields will be supported through specific nested aggregation support, and do not
+# work as expected when grouping on the root document type.
+returnfalseifnested?
+
+ # Text fields cannot be efficiently grouped on, so make them non-groupable by default.
+returnfalseiftext?
+
+ # In all other cases, default to being groupable.
+true
+ end
+
+ # Indicates if this field is aggregatable. Aggregatable fields will be available under `aggregatedValues` for an aggregations query.
+#
+# Aggregatability is inferred based on the field type and mapping type, or you can use the `aggregatable: true` option to force it.
+#
+# @return [Boolean]
+defaggregatable?
+ returnaggregatableunlessaggregatable.nil?
+ returnfalseifrelationship
+
+ # We don't yet support aggregating over subfields of a `nested` field.
+# TODO: add support for aggregating over subfields of `nested` fields.
+returnfalseifnested?
+
+ # Text fields are not efficiently aggregatable (and you'll often get errors from the datastore if you attempt to aggregate them).
+returnfalseiftext?
+
+ type_for_derived_types.fully_unwrapped.as_object_type&.supports?(&:aggregatable?)||index_leaf?
+ end
+
+ # Indicates if this field can be used as the basis for a sub-aggregation. Sub-aggregatable fields will be available under
+# `subAggregations` for an aggregations query.
+#
+# Only nested fields, and object fields which have nested fields, can be sub-aggregated.
+#
+# @return [Boolean]
+defsub_aggregatable?
+ returnfalseifrelationship
+
+ nested?||type_for_derived_types.fully_unwrapped.as_object_type&.supports?(&:sub_aggregatable?)
+ end
+
+ # Defines an argument on the field.
+#
+# @note ElasticGraph takes care of defining arguments for all the query features it supports, so there is generally no need to use
+# this API, and it has no way to interpret arbitrary arguments defined on a field. However, it can be useful for extensions that
+# extend the {ElasticGraph::GraphQL} query engine. For example, {ElasticGraph::Apollo} uses this API to satisfy the [Apollo
+# federation subgraph spec](https://www.apollographql.com/docs/federation/federation-spec/).
+#
+# @param name [String] name of the argument
+# @param value_type [String] type of the argument in GraphQL SDL syntax
+# @yield [Argument] for further customization
+#
+# @example Define an argument on a field
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Product" do |t|
+# t.field "name", "String" do |f|
+# f.argument "language", "String"
+# end
+# end
+# end
+defargument(name,value_type,&block)
+ args[name]=schema_def_state.factory.new_argument(
+ self,
+ name,
+ schema_def_state.type_ref(value_type),
+ &block
+ )
+ end
+
+ # The index mapping type in effect for this field. This could come from either the field definition or from the type definition.
+#
+# @return [String]
+defmapping_type
+ backing_indexing_field&.mapping_type||(resolve_mapping||{})["type"]
+ end
+
+ # @private
+deflist_field_groupable_by_single_values?
+ (type.list?||backing_indexing_field&.type&.list?)&&!singular_name.nil?
+ end
+
+ # @private
+defdefine_aggregated_values_field(parent_type)
+ returnunlessaggregatable?
+
+ unwrapped_type_for_derived_types=type_for_derived_types.fully_unwrapped
+ aggregated_values_type=
+ ifindex_leaf?
+ unwrapped_type_for_derived_types.resolved.aggregated_values_type
+ else
+ unwrapped_type_for_derived_types.as_aggregated_values
+ end
+
+ parent_type.fieldname,aggregated_values_type.name,name_in_index:name_in_index,graphql_only:truedo|f|
+ f.documentationderived_documentation("Computed aggregate values for the `#{name}` field")
+ aggregated_values_customizations.each{|block|block.call(f)}
+ end
+ end
+
+ # @private
+defdefine_grouped_by_field(parent_type)
+ returnunless(field_name=grouped_by_field_name)
+
+ parent_type.fieldfield_name,grouped_by_field_type_name,name_in_index:name_in_index,graphql_only:truedo|f|
+ add_grouped_by_field_documentation(f)
+
+ define_legacy_timestamp_grouping_arguments_if_needed(f)iflegacy_grouping_schema
+
+ grouped_by_customizations.each{|block|block.call(f)}
+ end
+ end
+
+ # @private
+defgrouped_by_field_type_name
+ unwrapped_type=type_for_derived_types.fully_unwrapped
+ ifunwrapped_type.scalar_type_needing_grouped_by_object?&&!legacy_grouping_schema
+ unwrapped_type.with_reverted_override.as_grouped_by.name
+ elsifunwrapped_type.leaf?
+ unwrapped_type.name
+ else
+ unwrapped_type.as_grouped_by.name
+ end
+ end
+
+ # @private
+defadd_grouped_by_field_documentation(field)
+ text=iflist_field_groupable_by_single_values?
+ derived_documentation(
+ "The individual value from `#{name}` for this group",
+ list_field_grouped_by_doc_note("`#{name}`")
+ )
+ elsiftype.list?&&type.fully_unwrapped.object?
+ derived_documentation(
+ "The `#{name}` field value for this group",
+ list_field_grouped_by_doc_note("the selected subfields of `#{name}`")
+ )
+ elsiftype_for_derived_types.fully_unwrapped.scalar_type_needing_grouped_by_object?&&!legacy_grouping_schema
+ derived_documentation("Offers the different grouping options for the `#{name}` value within this group")
+ else
+ derived_documentation("The `#{name}` field value for this group")
+ end
+
+ field.documentationtext
+ end
+
+ # @private
+defgrouped_by_field_name
+ returnnilunlessgroupable?
+ list_field_groupable_by_single_values??singular_name:name
+ end
+
+ # @private
+defdefine_sub_aggregations_field(parent_type:,type:)
+ parent_type.fieldname,type,name_in_index:name_in_index,graphql_only:truedo|f|
+ f.documentationderived_documentation("Used to perform a sub-aggregation of `#{name}`")
+ sub_aggregations_customizations.each{|c|c.call(f)}
+
+ yieldfifblock_given?
+ end
+ end
+
+ # @private
+defto_filter_field(parent_type:,for_single_value:!type_for_derived_types.list?)
+ type_prefix=text??"Text":type_for_derived_types.fully_unwrapped.name
+ filter_type=schema_def_state
+ .type_ref(type_prefix)
+ .as_static_derived_type(filter_field_category(for_single_value))
+ .name
+
+ params=to_h
+ .slice(*@@initialize_param_names)
+ .merge(type:filter_type,parent_type:parent_type,name_in_index:name_in_index,type_for_derived_types:nil)
+
+ schema_def_state.factory.new_field(**params).tapdo|f|
+ f.documentationderived_documentation(
+ "Used to filter on the `#{name}` field",
+ "Will be ignored if `null` or an empty object is passed"
+ )
+
+ filter_customizations.each{|c|c.call(f)}
+ end
+ end
+
+ # @private
+defdefine_relay_pagination_arguments!
+ argumentschema_def_state.schema_elements.first.to_sym,"Int"do|a|
+ a.documentation<<~EOS
+ Used in conjunction with the `after` argument to forward-paginate through the `#{name}`.
+ When provided, limits the number of returned results to the first `n` after the provided
+ `after` cursor (or from the start of the `#{name}`, if no `after` cursor is provided).
+
+ See the [Relay GraphQL Cursor Connections
+ Specification](https://relay.dev/graphql/connections.htm#sec-Arguments) for more info.
+ EOS
+end
+
+ argumentschema_def_state.schema_elements.after.to_sym,"Cursor"do|a|
+ a.documentation<<~EOS
+ Used to forward-paginate through the `#{name}`. When provided, the next page after the
+ provided cursor will be returned.
+
+ See the [Relay GraphQL Cursor Connections
+ Specification](https://relay.dev/graphql/connections.htm#sec-Arguments) for more info.
+ EOS
+end
+
+ argumentschema_def_state.schema_elements.last.to_sym,"Int"do|a|
+ a.documentation<<~EOS
+ Used in conjunction with the `before` argument to backward-paginate through the `#{name}`.
+ When provided, limits the number of returned results to the last `n` before the provided
+ `before` cursor (or from the end of the `#{name}`, if no `before` cursor is provided).
+
+ See the [Relay GraphQL Cursor Connections
+ Specification](https://relay.dev/graphql/connections.htm#sec-Arguments) for more info.
+ EOS
+end
+
+ argumentschema_def_state.schema_elements.before.to_sym,"Cursor"do|a|
+ a.documentation<<~EOS
+ Used to backward-paginate through the `#{name}`. When provided, the previous page before the
+ provided cursor will be returned.
+
+ See the [Relay GraphQL Cursor Connections
+ Specification](https://relay.dev/graphql/connections.htm#sec-Arguments) for more info.
+ EOS
+end
+ end
+
+ # Converts this field to an `Indexing::FieldReference`, which contains all the attributes involved
+# in building an `Indexing::Field`. Notably, we cannot actually convert to an `Indexing::Field` at
+# the point this method is called, because the referenced field type may not have been defined
+# yet. We don't need an actual `Indexing::Field` until the very end of the schema definition process,
+# when we are dumping the artifacts. However, we need this at field definition time so that we
+# can correctly detect duplicate indexing field issues when a field is defined. (This is used
+# in `TypeWithSubfields#field`).
+#
+# @private
+defto_indexing_field_reference
+ returnnilifgraphql_only
+
+ Indexing::FieldReference.new(
+ name:name,
+ name_in_index:name_in_index,
+ type:non_nullable_in_json_schema?type.wrap_non_null:type,
+ mapping_options:mapping_options,
+ json_schema_options:json_schema_options,
+ accuracy_confidence:accuracy_confidence,
+ source:source,
+ runtime_field_script:runtime_field_script
+ )
+ end
+
+ # Converts this field to its `IndexingField` form.
+#
+# @private
+defto_indexing_field
+ to_indexing_field_reference&.resolve
+ end
+
+ # @private
+defresolve_mapping
+ to_indexing_field&.mapping
+ end
+
+ # Returns the string paths to the list fields that we need to index counts for.
+# We do this to support the ability to filter on the size of a list.
+#
+# @private
+defpaths_to_lists_for_count_indexing(has_list_ancestor:false)
+ self_path=(has_list_ancestor||type.list?)?[name_in_index]:[]
+
+ nested_paths=
+ # Nested fields get indexed as separate hidden documents:
+# https://www.elastic.co/guide/en/elasticsearch/reference/8.8/nested.html
+#
+# Given that, the counts of any `nested` list subfields will go in a `__counts` field on the
+# separate hidden document.
+if!nested?&&(object_type=type.fully_unwrapped.as_object_type)
+ object_type.indexing_fields_by_name_in_index.values.flat_mapdo|sub_field|
+ sub_field.paths_to_lists_for_count_indexing(has_list_ancestor:has_list_ancestor||type.list?).mapdo|sub_path|
+ "#{name_in_index}#{LIST_COUNTS_FIELD_PATH_KEY_SEPARATOR}#{sub_path}"
+ end
+ end
+ else
+ []
+ end
+
+ self_path+nested_paths
+ end
+
+ # Indicates if this field is a leaf value in the index. Note that GraphQL leaf values
+# are always leaf values in the index but the inverse is not always true. For example,
+# a `GeoLocation` field is not a leaf in GraphQL (because `GeoLocation` is an object
+# type with subfields) but in the index we use a single `geo_point` mapping type, which
+# is a single unit, so we consider it an index leaf.
+#
+# @private
+defindex_leaf?
+ type_for_derived_types.fully_unwrapped.leaf?||DATASTORE_PROPERTYLESS_OBJECT_TYPES.include?(mapping_type)
+ end
+
+ # @private
+ACCURACY_SCORES={
+ # :high is assigned to `Field`s that are generated directly from GraphQL fields or :extra_fields.
+# For these, we know everything available to us in the schema about them.
+high:3,
+
+ # :medium is assigned to `Field`s that are inferred from the id fields required by a relation.
+# We make logical guesses about the `indexing_field_type` but if the field is also manually defined,
+# it could be slightly different (e.g. additional json schema validations), so we have medium
+# confidence of these.
+medium:2,
+
+ # :low is assigned to the ElastcField inferred for the foreign key of an inbound relation. The
+# nullability/cardinality of the foreign key field cannot be known from the relation metadata,
+# so we just guess what seems safest (`[:nullable]`). If the field is defined another way
+# we should prefer it, so we give these fields :low confidence.
+low:1
+ }
+
+ # Given two fields, picks the one that is most accurate. If they have the same accuracy
+# confidence, yields to a block to force it to deal with the discrepancy, unless the fields
+# are exactly equal (in which case we can return either).
+#
+# @private
+defself.pick_most_accurate_from(field1,field2,to_comparable:->(it){it})
+ returnfield1ifto_comparable.call(field1)==to_comparable.call(field2)
+ yieldiffield1.accuracy_confidence==field2.accuracy_confidence
+ # Array#max_by can return nil (when called on an empty array), but our steep type is non-nil.
+# Since it's not smart enough to realize the non-empty-array-usage of `max_by` won't return nil,
+# we have to cast it to untyped here.
+_=[field1,field2].max_by{|f|ACCURACY_SCORES.fetch(f.accuracy_confidence)}
+ end
+
+ # Indicates if the field uses the `nested` mapping type.
+#
+# @private
+defnested?
+ mapping_type=="nested"
+ end
+
+ # Records the `ComputationDetail` that should be on the `runtime_metadata_graphql_field`.
+#
+# @private
+defruntime_metadata_computation_detail(empty_bucket_value:,function:)
+ self.computation_detail=SchemaArtifacts::RuntimeMetadata::ComputationDetail.new(
+ empty_bucket_value:empty_bucket_value,
+ function:function
+ )
+ end
+
+ # Lazily creates and returns a GraphQLField using the field's {#name_in_index}, {#computation_detail},
+# and {#relationship}.
+#
+# @private
+defruntime_metadata_graphql_field
+ SchemaArtifacts::RuntimeMetadata::GraphQLField.new(
+ name_in_index:name_in_index,
+ computation_detail:computation_detail,
+ relation:relationship&.runtime_metadata
+ )
+ end
+
+ private
+
+ defargs_sdl(joiner:,after_opening_paren:"",&arg_selector)
+ selected_args=args.values.select(&arg_selector)
+ args_sdl=selected_args.map(&:to_sdl).flat_map{|s|s.split("\n")}.join(joiner)
+ returnnilifargs_sdl.empty?
+ "(#{after_opening_paren}#{args_sdl})"
+ end
+
+ # Indicates if the field uses the `text` mapping type.
+deftext?
+ mapping_type=="text"
+ end
+
+ defdefine_legacy_timestamp_grouping_arguments_if_needed(grouping_field)
+ casetype.fully_unwrapped.name
+ when"Date"
+ grouping_field.argumentschema_def_state.schema_elements.granularity,"DateGroupingGranularity!"do|a|
+ a.documentation"Determines the grouping granularity for this field."
+ end
+
+ grouping_field.argumentschema_def_state.schema_elements.offset_days,"Int"do|a|
+ a.documentation<<~EOS
+ Number of days (positive or negative) to shift the `Date` boundaries of each date grouping bucket.
+
+ For example, when grouping by `YEAR`, this can be used to align the buckets with fiscal or school years instead of calendar years.
+ EOS
+end
+ when"DateTime"
+ grouping_field.argumentschema_def_state.schema_elements.granularity,"DateTimeGroupingGranularity!"do|a|
+ a.documentation"Determines the grouping granularity for this field."
+ end
+
+ grouping_field.argumentschema_def_state.schema_elements.time_zone,"TimeZone"do|a|
+ a.documentation"The time zone to use when determining which grouping a `DateTime` value falls in."
+ a.default"UTC"
+ end
+
+ grouping_field.argumentschema_def_state.schema_elements.offset,"DateTimeGroupingOffsetInput"do|a|
+ a.documentation<<~EOS
+ Amount of offset (positive or negative) to shift the `DateTime` boundaries of each grouping bucket.
+
+ For example, when grouping by `WEEK`, you can shift by 24 hours to change what day-of-week weeks are considered to start on.
+ EOS
+end
+ end
+ end
+
+ deflist_field_grouped_by_doc_note(individual_value_selection_description)
+ <<~EOS.strip
+ Note: `#{name}` is a collection field, but selecting this field will group on individual values of #{individual_value_selection_description}.
+ That means that a document may be grouped into multiple aggregation groupings (i.e. when its `#{name}`
+ field has multiple values) leading to some data duplication in the response. However, if a value shows
+ up in `#{name}` multiple times for a single document, that document will only be included in the group
+ once
+ EOS
+end
+
+ # Determines the suffix of the filter field derived for this field. The suffix used determines
+# the filtering capabilities (e.g. filtering on a single value vs a list of values with `any_satisfy`).
+deffilter_field_category(for_single_value)
+ return:filter_inputiffor_single_value
+
+ # For an index leaf field, there are no further nesting paths to traverse. We want to directly
+# use a `ListFilterInput` type (e.g. `IntListFilterInput`) to offer `any_satisfy` filtering at this level.
+return:list_filter_inputifindex_leaf?
+
+ # If it's a list-of-objects field we require the user to tell us what mapping type they want to
+# use, which determines the suffix (and is handled below). Otherwise, we want to use `FieldsListFilterInput`.
+# We are within a list filtering context (as indicated by `for_single_value` being false) without
+# being at an index leaf field, so we must use `FieldsListFilterInput` as there are further nesting paths
+# on the document and we want to provide `any_satisfy` at the leaf fields.
+return:fields_list_filter_inputunlesstype_for_derived_types.list?
+
+ casemapping_type
+ when"nested"then:list_filter_input
+ when"object"then:fields_list_filter_input
+ else
+ raiseErrors::SchemaError,<<~EOS
+ `#{parent_type.name}.#{name}` is a list-of-objects field, but the mapping type has not been explicitly specified. Elasticsearch and OpenSearch
+ offer two ways to index list-of-objects fields. It cannot be changed on an existing field without dropping the index and recreating it (losing
+ any existing indexed data!), and there are nuanced tradeoffs involved here, so ElasticGraph provides no default mapping in this situation.
+
+ If you're currently prototyping and don't want to spend time weighing this tradeoff, we recommend you do this:
+
+ ```
+ t.field "#{name}", "#{type.name}" do |f|
+ # Here we are opting for flexibility (nested) over pure performance (object).
+ # TODO: evaluate if we want to stick with `nested` before going to production.
+ f.mapping type: "nested"
+ end
+ ```
+
+ Read on for details of the tradeoff involved here.
+
+ -----------------------------------------------------------------------------------------------------------------------------
+
+ Here are the options:
+
+ 1) `f.mapping type: "object"` will cause each field path to be indexed as a separate "flattened" list.
+
+ For example, given a `Film` document like this:
+
+ ```
+ {
+ "name": "The Empire Strikes Back",
+ "characters": [
+ {"first": "Luke", "last": "Skywalker"},
+ {"first": "Han", "last": "Solo"}
+ ]
+ }
+ ```
+
+ ...the data will look like this in the inverted Lucene index:
+
+ ```
+ {
+ "name": "The Empire Strikes Back",
+ "characters.first": ["Luke", "Han"],
+ "characters.last": ["Skywalker", "Solo"]
+ }
+ ```
+
+ This is highly efficient, but there is no way to search on multiple fields of a character and be sure that the matching values came from the same character.
+ ElasticGraph models this in the filtering API it offers for this case:
+
+ ```
+ query {
+ films(filter: {
+ characters: {
+ first: {#{schema_def_state.schema_elements.any_satisfy}: {#{schema_def_state.schema_elements.equal_to_any_of}: ["Luke"]}}
+ last: {#{schema_def_state.schema_elements.any_satisfy}: {#{schema_def_state.schema_elements.equal_to_any_of}: ["Skywalker"]}}
+ }
+ }) {
+ # ...
+ }
+ }
+ ```
+
+ As suggested by this filtering API, this will match any film that has a character with a first name of "Luke" and a character
+ with the last name of "Skywalker", but this could be satisfied by two separate characters.
+
+ 2) `f.mapping type: "nested"` will cause each _object_ in the list to be indexed as a separate hidden document, preserving the independence of each.
+
+ Given a `Film` document like "The Empire Strikes Back" from above, the `nested` type will index separate hidden documents for each character. This
+ allows ElasticGraph to offer this filtering API instead:
+
+ ```
+ query {
+ films(filter: {
+ characters: {#{schema_def_state.schema_elements.any_satisfy}: {
+ first: {#{schema_def_state.schema_elements.equal_to_any_of}: ["Luke"]}
+ last: {#{schema_def_state.schema_elements.equal_to_any_of}: ["Skywalker"]}
+ }}
+ }) {
+ # ...
+ }
+ }
+ ```
+
+ As suggested by this filtering API, this will only match films that have a character named "Luke Skywalker". However, the Elasticsearch docs[^1][^2] warn
+ that the `nested` mapping type can lead to performance problems, and index sorting cannot be configured[^3] when the `nested` type is used.
+
+ [^1]: https://www.elastic.co/guide/en/elasticsearch/reference/8.10/nested.html
+ [^2]: https://www.elastic.co/guide/en/elasticsearch/reference/8.10/joining-queries.html
+ [^3]: https://www.elastic.co/guide/en/elasticsearch/reference/8.10/index-modules-index-sorting.html
+ EOS
+end
+ end
+end
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/schema_elements/field.rb', line 89
+
+classField<Struct.new(
+ :name,:original_type,:parent_type,:original_type_for_derived_types,:schema_def_state,:accuracy_confidence,
+ :filter_customizations,:grouped_by_customizations,:sub_aggregations_customizations,
+ :aggregated_values_customizations,:sort_order_enum_value_customizations,
+ :args,:sortable,:filterable,:aggregatable,:groupable,:graphql_only,:source,:runtime_field_script,:relationship,:singular_name,
+ :computation_detail,:non_nullable_in_json_schema,:backing_indexing_field,:as_input,
+ :legacy_grouping_schema,:name_in_index
+)
+ includeMixins::HasDocumentation
+ includeMixins::HasDirectives
+ includeMixins::HasTypeInfo
+ includeMixins::HasReadableToSAndInspect.new{|f|"#{f.parent_type.name}.#{f.name}: #{f.type}"}
+
+ # @private
+definitialize(
+ name:,type:,parent_type:,schema_def_state:,
+ accuracy_confidence::high,name_in_index:name,
+ runtime_metadata_graphql_field:SchemaArtifacts::RuntimeMetadata::GraphQLField::EMPTY,
+ type_for_derived_types:nil,graphql_only:nil,singular:nil,
+ sortable:nil,filterable:nil,aggregatable:nil,groupable:nil,
+ backing_indexing_field:nil,as_input:false,legacy_grouping_schema:false
+ )
+ type_ref=schema_def_state.type_ref(type)
+ super(
+ name:name,
+ original_type:type_ref,
+ parent_type:parent_type,
+ original_type_for_derived_types:type_for_derived_types?schema_def_state.type_ref(type_for_derived_types):type_ref,
+ schema_def_state:schema_def_state,
+ accuracy_confidence:accuracy_confidence,
+ filter_customizations:[],
+ grouped_by_customizations:[],
+ sub_aggregations_customizations:[],
+ aggregated_values_customizations:[],
+ sort_order_enum_value_customizations:[],
+ args:{},
+ sortable:sortable,
+ filterable:filterable,
+ aggregatable:aggregatable,
+ groupable:groupable,
+ graphql_only:graphql_only,
+ source:nil,
+ runtime_field_script:nil,
+ # Note: we named the keyword argument `singular` (with no `_name` suffix) for consistency with
+# other schema definition APIs, which also use `singular:` instead of `singular_name:`. We include
+# the `_name` suffix on the attribute for clarity.
+singular_name:singular,
+ name_in_index:name_in_index,
+ non_nullable_in_json_schema:false,
+ backing_indexing_field:backing_indexing_field,
+ as_input:as_input,
+ legacy_grouping_schema:legacy_grouping_schema
+ )
+
+ ifname!=name_in_index&&name_in_index&.include?(".")&&!graphql_only
+ raiseErrors::SchemaError,"#{self} has an invalid `name_in_index`: #{name_in_index.inspect}. Only `graphql_only: true` fields can have a `name_in_index` that references a child field."
+ end
+
+ schema_def_state.register_user_defined_field(self)
+ yieldselfifblock_given?
+ end
+
+ # @private
+@@initialize_param_names=instance_method(:initialize).parameters.map(&:last).to_set
+
+ # must come after we capture the initialize params.
+prependMixins::VerifiesGraphQLName
+
+ # @return [TypeReference] the type of this field
+deftype
+ # Here we lazily convert the `original_type` to an input type as needed. This must be lazy because
+# the logic of `as_input` depends on detecting whether the type is an enum type, which it may not
+# be able to do right away--we assume not if we can't tell, and retry every time this method is called.
+original_type.to_final_form(as_input:as_input)
+ end
+
+ # @return [TypeReference] the type of the corresponding field on derived types (usually this is the same as {#type}).
+#
+# @private
+deftype_for_derived_types
+ original_type_for_derived_types.to_final_form(as_input:as_input)
+ end
+
+ # @note For each field defined in your schema that is filterable, a corresponding filtering field will be created on the
+# `*FilterInput` type derived from the parent object type.
+#
+# Registers a customization callback that will be applied to the corresponding filtering field that will be generated for this
+# field.
+#
+# @yield [Field] derived filtering field
+# @return [void]
+# @see #customize_aggregated_values_field
+# @see #customize_grouped_by_field
+# @see #customize_sort_order_enum_values
+# @see #customize_sub_aggregations_field
+# @see #on_each_generated_schema_element
+#
+# @example Mark `CampaignFilterInput.organizationId` with `@deprecated`
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Campaign" do |t|
+# t.field "id", "ID"
+#
+# t.field "organizationId", "ID" do |f|
+# f.customize_filter_field do |ff|
+# ff.directive "deprecated"
+# end
+# end
+#
+# t.index "campaigns"
+# end
+# end
+defcustomize_filter_field(&customization_block)
+ filter_customizations<<customization_block
+ end
+
+ # @note For each field defined in your schema that is aggregatable, a corresponding `aggregatedValues` field will be created on the
+# `*AggregatedValues` type derived from the parent object type.
+#
+# Registers a customization callback that will be applied to the corresponding `aggregatedValues` field that will be generated for
+# this field.
+#
+# @yield [Field] derived aggregated values field
+# @return [void]
+# @see #customize_filter_field
+# @see #customize_grouped_by_field
+# @see #customize_sort_order_enum_values
+# @see #customize_sub_aggregations_field
+# @see #on_each_generated_schema_element
+#
+# @example Mark `CampaignAggregatedValues.adImpressions` with `@deprecated`
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Campaign" do |t|
+# t.field "id", "ID"
+#
+# t.field "adImpressions", "Int" do |f|
+# f.customize_aggregated_values_field do |avf|
+# avf.directive "deprecated"
+# end
+# end
+#
+# t.index "campaigns"
+# end
+# end
+defcustomize_aggregated_values_field(&customization_block)
+ aggregated_values_customizations<<customization_block
+ end
+
+ # @note For each field defined in your schema that is groupable, a corresponding `groupedBy` field will be created on the
+# `*AggregationGroupedBy` type derived from the parent object type.
+#
+# Registers a customization callback that will be applied to the corresponding `groupedBy` field that will be generated for this
+# field.
+#
+# @yield [Field] derived grouped by field
+# @return [void]
+# @see #customize_aggregated_values_field
+# @see #customize_filter_field
+# @see #customize_sort_order_enum_values
+# @see #customize_sub_aggregations_field
+# @see #on_each_generated_schema_element
+#
+# @example Mark `CampaignGroupedBy.organizationId` with `@deprecated`
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Campaign" do |t|
+# t.field "id", "ID"
+#
+# t.field "organizationId", "ID" do |f|
+# f.customize_grouped_by_field do |gbf|
+# gbf.directive "deprecated"
+# end
+# end
+#
+# t.index "campaigns"
+# end
+# end
+defcustomize_grouped_by_field(&customization_block)
+ grouped_by_customizations<<customization_block
+ end
+
+ # @note For each field defined in your schema that is sub-aggregatable (e.g. list fields indexed using the `nested` mapping type),
+# a corresponding field will be created on the `*AggregationSubAggregations` type derived from the parent object type.
+#
+# Registers a customization callback that will be applied to the corresponding `subAggregations` field that will be generated for
+# this field.
+#
+# @yield [Field] derived sub-aggregations field
+# @return [void]
+# @see #customize_aggregated_values_field
+# @see #customize_filter_field
+# @see #customize_grouped_by_field
+# @see #customize_sort_order_enum_values
+# @see #on_each_generated_schema_element
+#
+# @example Mark `TransactionAggregationSubAggregations.fees` with `@deprecated`
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Transaction" do |t|
+# t.field "id", "ID"
+#
+# t.field "fees", "[Money!]!" do |f|
+# f.mapping type: "nested"
+#
+# f.customize_sub_aggregations_field do |saf|
+# # Adds a `@deprecated` directive to the `PaymentAggregationSubAggregations.fees`
+# # field without also adding it to the `Payment.fees` field.
+# saf.directive "deprecated"
+# end
+# end
+#
+# t.index "transactions"
+# end
+#
+# schema.object_type "Money" do |t|
+# t.field "amount", "Int"
+# t.field "currency", "String"
+# end
+# end
+defcustomize_sub_aggregations_field(&customization_block)
+ sub_aggregations_customizations<<customization_block
+ end
+
+ # @note for each sortable field, enum values will be generated on the derived sort order enum type allowing you to
+# sort by the field `ASC` or `DESC`.
+#
+# Registers a customization callback that will be applied to the corresponding enum values that will be generated for this field
+# on the derived `SortOrder` enum type.
+#
+# @yield [SortOrderEnumValue] derived sort order enum value
+# @return [void]
+# @see #customize_aggregated_values_field
+# @see #customize_filter_field
+# @see #customize_grouped_by_field
+# @see #customize_sub_aggregations_field
+# @see #on_each_generated_schema_element
+#
+# @example Mark `CampaignSortOrder.organizationId_(ASC|DESC)` with `@deprecated`
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Campaign" do |t|
+# t.field "id", "ID"
+#
+# t.field "organizationId", "ID" do |f|
+# f.customize_sort_order_enum_values do |soev|
+# soev.directive "deprecated"
+# end
+# end
+#
+# t.index "campaigns"
+# end
+# end
+defcustomize_sort_order_enum_values(&customization_block)
+ sort_order_enum_value_customizations<<customization_block
+ end
+
+ # When you define a {Field} on an {ObjectType} or {InterfaceType}, ElasticGraph generates up to 6 different GraphQL schema elements
+# for it:
+#
+# * A {Field} is generated on the parent {ObjectType} or {InterfaceType} (that is, this field itself). This is used by clients to
+# ask for values for the field in a response.
+# * A {Field} may be generated on the `*FilterInput` {InputType} derived from the parent {ObjectType} or {InterfaceType}. This is
+# used by clients to specify how the query should filter.
+# * A {Field} may be generated on the `*AggregationGroupedBy` {ObjectType} derived from the parent {ObjectType} or {InterfaceType}.
+# This is used by clients to specify how aggregations should be grouped.
+# * A {Field} may be generated on the `*AggregatedValues` {ObjectType} derived from the parent {ObjectType} or {InterfaceType}.
+# This is used by clients to apply aggregation functions (e.g. `sum`, `max`, `min`, etc) to a set of field values for a group.
+# * A {Field} may be generated on the `*AggregationSubAggregations` {ObjectType} derived from the parent {ObjectType} or
+# {InterfaceType}. This is used by clients to perform sub-aggregations on list fields indexed using the `nested` mapping type.
+# * Multiple {EnumValue}s (both `*_ASC` and `*_DESC`) are generated on the `*SortOrder` {EnumType} derived from the parent indexed
+# {ObjectType}. This is used by clients to sort by a field.
+#
+# This method registers a customization callback which is applied to every element that is generated for this field.
+#
+# @yield [Field, EnumValue] the schema element
+# @return [void]
+# @see #customize_aggregated_values_field
+# @see #customize_filter_field
+# @see #customize_grouped_by_field
+# @see #customize_sort_order_enum_values
+# @see #customize_sub_aggregations_field
+#
+# @example
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Transaction" do |t|
+# t.field "id", "ID"
+#
+# t.field "amount", "Int" do |f|
+# f.on_each_generated_schema_element do |element|
+# # Adds a `@deprecated` directive to every GraphQL schema element generated for `amount`:
+# #
+# # - The `Transaction.amount` field.
+# # - The `TransactionFilterInput.amount` field.
+# # - The `TransactionAggregationGroupedBy.amount` field.
+# # - The `TransactionAggregatedValues.amount` field.
+# # - The `TransactionSortOrder.amount_ASC` and`TransactionSortOrder.amount_DESC` enum values.
+# element.directive "deprecated"
+# end
+# end
+#
+# t.index "transactions"
+# end
+# end
+defon_each_generated_schema_element(&customization_block)
+ customization_block.call(self)
+ customize_filter_field(&customization_block)
+ customize_aggregated_values_field(&customization_block)
+ customize_grouped_by_field(&customization_block)
+ customize_sub_aggregations_field(&customization_block)
+ customize_sort_order_enum_values(&customization_block)
+ end
+
+ # (see Mixins::HasTypeInfo#json_schema)
+defjson_schema(nullable:nil,**options)
+ ifoptions.key?(:type)
+ raiseErrors::SchemaError,"Cannot override JSON schema type of field `#{name}` with `#{options.fetch(:type)}`"
+ end
+
+ casenullable
+ whentrue
+ raiseErrors::SchemaError,"`nullable: true` is not allowed on a field--just declare the GraphQL field as being nullable (no `!` suffix) instead."
+ whenfalse
+ self.non_nullable_in_json_schema=true
+ end
+
+ super(**options)
+ end
+
+ # Configures ElasticGraph to source a field’s value from a related object. This can be used to denormalize data at ingestion time to
+# support filtering, grouping, sorting, or aggregating data on a field from a related object.
+#
+# @param relationship [String] name of a relationship defined with {TypeWithSubfields#relates_to_one} using an inbound foreign key
+# which contains the the field you wish to source values from
+# @param field_path [String] dot-separated path to the field on the related type containing values that should be copied to this
+# field
+# @return [void]
+#
+# @example Source `City.currency` from `Country.currency`
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Country" do |t|
+# t.field "id", "ID"
+# t.field "name", "String"
+# t.field "currency", "String"
+# t.relates_to_one "capitalCity", "City", via: "capitalCityId", dir: :out
+# t.index "countries"
+# end
+#
+# schema.object_type "City" do |t|
+# t.field "id", "ID"
+# t.field "name", "String"
+# t.relates_to_one "capitalOf", "Country", via: "capitalCityId", dir: :in
+#
+# t.field "currency", "String" do |f|
+# f.sourced_from "capitalOf", "currency"
+# end
+#
+# t.index "cities"
+# end
+# end
+defsourced_from(relationship,field_path)
+ self.source=schema_def_state.factory.new_field_source(
+ relationship_name:relationship,
+ field_path:field_path
+ )
+ end
+
+ # @private
+defruntime_script(script)
+ self.runtime_field_script=script
+ end
+
+ # Registers an old name that this field used to have in a prior version of the schema.
+#
+# @note In situations where this API applies, ElasticGraph will give you an error message indicating that you need to use this API
+# or {TypeWithSubfields#deleted_field}. Likewise, when ElasticGraph no longer needs to know about this, it'll give you a warning
+# indicating the call to this method can be removed.
+#
+# @param old_name [String] old name this field used to have in a prior version of the schema
+# @return [void]
+#
+# @example Indicate that `Widget.description` used to be called `Widget.notes`.
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Widget" do |t|
+# t.field "description", "String" do |f|
+# f.renamed_from "notes"
+# end
+# end
+# end
+defrenamed_from(old_name)
+ schema_def_state.register_renamed_field(
+ parent_type.name,
+ from:old_name,
+ to:name,
+ defined_at:caller_locations(1,1).first,# : ::Thread::Backtrace::Location
+defined_via:%(field.renamed_from "#{old_name}")
+ )
+ end
+
+ # @private
+defto_sdl(type_structure_only:false,default_value_sdl:nil,&arg_selector)
+ iftype_structure_only
+ "#{name}#{args_sdl(joiner:", ",&arg_selector)}: #{type.name}"
+ else
+ args_sdl=args_sdl(joiner:"\n ",after_opening_paren:"\n ",&arg_selector)
+ "#{formatted_documentation}#{name}#{args_sdl}: #{type.name}#{default_value_sdl}#{directives_sdl}".strip
+ end
+ end
+
+ # Indicates if this field is sortable. Sortable fields will have corresponding `_ASC` and `_DESC` values generated in the
+# sort order {EnumType} of the parent indexed type.
+#
+# By default, the sortability is inferred by the field type and mapping. For example, list fields are not sortable,
+# and fields mapped as `text` are not sortable either. Fields are sortable in most other cases.
+#
+# The `sortable: true` option can be used to force a field to be sortable.
+#
+# @return [Boolean] true if this field is sortable
+defsortable?
+ returnsortableunlesssortable.nil?
+
+ # List fields are not sortable by default. We'd need to provide the datastore a sort mode option:
+# https://www.elastic.co/guide/en/elasticsearch/reference/current/sort-search-results.html#_sort_mode_option
+returnfalseiftype.list?
+
+ # Boolean fields are not sortable by default.
+# - Boolean: sorting all falses before all trues (or whatever) is not generally interesting.
+returnfalseiftype.unwrap_non_null.boolean?
+
+ # Elasticsearch/OpenSearch do not support sorting text fields:
+# > Text fields are not used for sorting...
+# (from https://www.elastic.co/guide/en/elasticsearch/reference/current/the datastore.html#text)
+returnfalseiftext?
+
+ # If the type uses custom mapping type we don't know how if the datastore can sort by it, so we assume it's not sortable.
+returnfalseiftype.as_object_type&.has_custom_mapping_type?
+
+ # Default every other field to being sortable.
+true
+ end
+
+ # Indicates if this field is filterable. Filterable fields will be available in the GraphQL schema under the `filter` argument.
+#
+# Most fields are filterable, except when:
+#
+# - It's a relation. Relation fields require us to load the related data from another index and can't be filtered on.
+# - The field is an object type that isn't itself filterable (e.g. due to having no filterable fields or whatever).
+# - Explicitly disabled with `filterable: false`.
+#
+# @return [Boolean]
+deffilterable?
+ # Object types that use custom index mappings (as `GeoLocation` does) aren't filterable
+# by default since we can't guess what datastore filtering capabilities they have. We've implemented
+# filtering support for `GeoLocation` fields, though, so we need to explicitly make it fliterable here.
+# TODO: clean this up using an interface instead of checking for `GeoLocation`.
+returntrueiftype.fully_unwrapped.name=="GeoLocation"
+
+ returnfalseifrelationship||type.fully_unwrapped.as_object_type&.does_not_support?(&:filterable?)
+ returntrueiffilterable.nil?
+ filterable
+ end
+
+ # Indicates if this field is groupable. Groupable fields will be available under `groupedBy` for an aggregations query.
+#
+# Groupability is inferred based on the field type and mapping type, or you can use the `groupable: true` option to force it.
+#
+# @return [Boolean]
+defgroupable?
+ # If the groupability of the field was specified explicitly when the field was defined, use the specified value.
+returngroupableunlessgroupable.nil?
+
+ # We don't want the `id` field of an indexed type to be available to group by, because it's the unique primary key
+# and the groupings would each contain one document. It's simpler and more efficient to just query the raw documents
+# instead.
+returnfalseifparent_type.indexed?&&name=="id"
+
+ returnfalseifrelationship||type.fully_unwrapped.as_object_type&.does_not_support?(&:groupable?)
+
+ # We don't support grouping an entire list of values, but we do support grouping on individual values in a list.
+# However, we only do so when a `singular_name` has been provided (so that we know what to call the grouped_by field).
+# The semantics are a little odd (since one document can be duplicated in multiple grouping buckets) so we're ok
+# with not offering it by default--the user has to opt-in by telling us what to call the field in its singular form.
+returnlist_field_groupable_by_single_values?iftype.list?&&type.fully_unwrapped.leaf?
+
+ # Nested fields will be supported through specific nested aggregation support, and do not
+# work as expected when grouping on the root document type.
+returnfalseifnested?
+
+ # Text fields cannot be efficiently grouped on, so make them non-groupable by default.
+returnfalseiftext?
+
+ # In all other cases, default to being groupable.
+true
+ end
+
+ # Indicates if this field is aggregatable. Aggregatable fields will be available under `aggregatedValues` for an aggregations query.
+#
+# Aggregatability is inferred based on the field type and mapping type, or you can use the `aggregatable: true` option to force it.
+#
+# @return [Boolean]
+defaggregatable?
+ returnaggregatableunlessaggregatable.nil?
+ returnfalseifrelationship
+
+ # We don't yet support aggregating over subfields of a `nested` field.
+# TODO: add support for aggregating over subfields of `nested` fields.
+returnfalseifnested?
+
+ # Text fields are not efficiently aggregatable (and you'll often get errors from the datastore if you attempt to aggregate them).
+returnfalseiftext?
+
+ type_for_derived_types.fully_unwrapped.as_object_type&.supports?(&:aggregatable?)||index_leaf?
+ end
+
+ # Indicates if this field can be used as the basis for a sub-aggregation. Sub-aggregatable fields will be available under
+# `subAggregations` for an aggregations query.
+#
+# Only nested fields, and object fields which have nested fields, can be sub-aggregated.
+#
+# @return [Boolean]
+defsub_aggregatable?
+ returnfalseifrelationship
+
+ nested?||type_for_derived_types.fully_unwrapped.as_object_type&.supports?(&:sub_aggregatable?)
+ end
+
+ # Defines an argument on the field.
+#
+# @note ElasticGraph takes care of defining arguments for all the query features it supports, so there is generally no need to use
+# this API, and it has no way to interpret arbitrary arguments defined on a field. However, it can be useful for extensions that
+# extend the {ElasticGraph::GraphQL} query engine. For example, {ElasticGraph::Apollo} uses this API to satisfy the [Apollo
+# federation subgraph spec](https://www.apollographql.com/docs/federation/federation-spec/).
+#
+# @param name [String] name of the argument
+# @param value_type [String] type of the argument in GraphQL SDL syntax
+# @yield [Argument] for further customization
+#
+# @example Define an argument on a field
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Product" do |t|
+# t.field "name", "String" do |f|
+# f.argument "language", "String"
+# end
+# end
+# end
+defargument(name,value_type,&block)
+ args[name]=schema_def_state.factory.new_argument(
+ self,
+ name,
+ schema_def_state.type_ref(value_type),
+ &block
+ )
+ end
+
+ # The index mapping type in effect for this field. This could come from either the field definition or from the type definition.
+#
+# @return [String]
+defmapping_type
+ backing_indexing_field&.mapping_type||(resolve_mapping||{})["type"]
+ end
+
+ # @private
+deflist_field_groupable_by_single_values?
+ (type.list?||backing_indexing_field&.type&.list?)&&!singular_name.nil?
+ end
+
+ # @private
+defdefine_aggregated_values_field(parent_type)
+ returnunlessaggregatable?
+
+ unwrapped_type_for_derived_types=type_for_derived_types.fully_unwrapped
+ aggregated_values_type=
+ ifindex_leaf?
+ unwrapped_type_for_derived_types.resolved.aggregated_values_type
+ else
+ unwrapped_type_for_derived_types.as_aggregated_values
+ end
+
+ parent_type.fieldname,aggregated_values_type.name,name_in_index:name_in_index,graphql_only:truedo|f|
+ f.documentationderived_documentation("Computed aggregate values for the `#{name}` field")
+ aggregated_values_customizations.each{|block|block.call(f)}
+ end
+ end
+
+ # @private
+defdefine_grouped_by_field(parent_type)
+ returnunless(field_name=grouped_by_field_name)
+
+ parent_type.fieldfield_name,grouped_by_field_type_name,name_in_index:name_in_index,graphql_only:truedo|f|
+ add_grouped_by_field_documentation(f)
+
+ define_legacy_timestamp_grouping_arguments_if_needed(f)iflegacy_grouping_schema
+
+ grouped_by_customizations.each{|block|block.call(f)}
+ end
+ end
+
+ # @private
+defgrouped_by_field_type_name
+ unwrapped_type=type_for_derived_types.fully_unwrapped
+ ifunwrapped_type.scalar_type_needing_grouped_by_object?&&!legacy_grouping_schema
+ unwrapped_type.with_reverted_override.as_grouped_by.name
+ elsifunwrapped_type.leaf?
+ unwrapped_type.name
+ else
+ unwrapped_type.as_grouped_by.name
+ end
+ end
+
+ # @private
+defadd_grouped_by_field_documentation(field)
+ text=iflist_field_groupable_by_single_values?
+ derived_documentation(
+ "The individual value from `#{name}` for this group",
+ list_field_grouped_by_doc_note("`#{name}`")
+ )
+ elsiftype.list?&&type.fully_unwrapped.object?
+ derived_documentation(
+ "The `#{name}` field value for this group",
+ list_field_grouped_by_doc_note("the selected subfields of `#{name}`")
+ )
+ elsiftype_for_derived_types.fully_unwrapped.scalar_type_needing_grouped_by_object?&&!legacy_grouping_schema
+ derived_documentation("Offers the different grouping options for the `#{name}` value within this group")
+ else
+ derived_documentation("The `#{name}` field value for this group")
+ end
+
+ field.documentationtext
+ end
+
+ # @private
+defgrouped_by_field_name
+ returnnilunlessgroupable?
+ list_field_groupable_by_single_values??singular_name:name
+ end
+
+ # @private
+defdefine_sub_aggregations_field(parent_type:,type:)
+ parent_type.fieldname,type,name_in_index:name_in_index,graphql_only:truedo|f|
+ f.documentationderived_documentation("Used to perform a sub-aggregation of `#{name}`")
+ sub_aggregations_customizations.each{|c|c.call(f)}
+
+ yieldfifblock_given?
+ end
+ end
+
+ # @private
+defto_filter_field(parent_type:,for_single_value:!type_for_derived_types.list?)
+ type_prefix=text??"Text":type_for_derived_types.fully_unwrapped.name
+ filter_type=schema_def_state
+ .type_ref(type_prefix)
+ .as_static_derived_type(filter_field_category(for_single_value))
+ .name
+
+ params=to_h
+ .slice(*@@initialize_param_names)
+ .merge(type:filter_type,parent_type:parent_type,name_in_index:name_in_index,type_for_derived_types:nil)
+
+ schema_def_state.factory.new_field(**params).tapdo|f|
+ f.documentationderived_documentation(
+ "Used to filter on the `#{name}` field",
+ "Will be ignored if `null` or an empty object is passed"
+ )
+
+ filter_customizations.each{|c|c.call(f)}
+ end
+ end
+
+ # @private
+defdefine_relay_pagination_arguments!
+ argumentschema_def_state.schema_elements.first.to_sym,"Int"do|a|
+ a.documentation<<~EOS
+ Used in conjunction with the `after` argument to forward-paginate through the `#{name}`.
+ When provided, limits the number of returned results to the first `n` after the provided
+ `after` cursor (or from the start of the `#{name}`, if no `after` cursor is provided).
+
+ See the [Relay GraphQL Cursor Connections
+ Specification](https://relay.dev/graphql/connections.htm#sec-Arguments) for more info.
+ EOS
+end
+
+ argumentschema_def_state.schema_elements.after.to_sym,"Cursor"do|a|
+ a.documentation<<~EOS
+ Used to forward-paginate through the `#{name}`. When provided, the next page after the
+ provided cursor will be returned.
+
+ See the [Relay GraphQL Cursor Connections
+ Specification](https://relay.dev/graphql/connections.htm#sec-Arguments) for more info.
+ EOS
+end
+
+ argumentschema_def_state.schema_elements.last.to_sym,"Int"do|a|
+ a.documentation<<~EOS
+ Used in conjunction with the `before` argument to backward-paginate through the `#{name}`.
+ When provided, limits the number of returned results to the last `n` before the provided
+ `before` cursor (or from the end of the `#{name}`, if no `before` cursor is provided).
+
+ See the [Relay GraphQL Cursor Connections
+ Specification](https://relay.dev/graphql/connections.htm#sec-Arguments) for more info.
+ EOS
+end
+
+ argumentschema_def_state.schema_elements.before.to_sym,"Cursor"do|a|
+ a.documentation<<~EOS
+ Used to backward-paginate through the `#{name}`. When provided, the previous page before the
+ provided cursor will be returned.
+
+ See the [Relay GraphQL Cursor Connections
+ Specification](https://relay.dev/graphql/connections.htm#sec-Arguments) for more info.
+ EOS
+end
+ end
+
+ # Converts this field to an `Indexing::FieldReference`, which contains all the attributes involved
+# in building an `Indexing::Field`. Notably, we cannot actually convert to an `Indexing::Field` at
+# the point this method is called, because the referenced field type may not have been defined
+# yet. We don't need an actual `Indexing::Field` until the very end of the schema definition process,
+# when we are dumping the artifacts. However, we need this at field definition time so that we
+# can correctly detect duplicate indexing field issues when a field is defined. (This is used
+# in `TypeWithSubfields#field`).
+#
+# @private
+defto_indexing_field_reference
+ returnnilifgraphql_only
+
+ Indexing::FieldReference.new(
+ name:name,
+ name_in_index:name_in_index,
+ type:non_nullable_in_json_schema?type.wrap_non_null:type,
+ mapping_options:mapping_options,
+ json_schema_options:json_schema_options,
+ accuracy_confidence:accuracy_confidence,
+ source:source,
+ runtime_field_script:runtime_field_script
+ )
+ end
+
+ # Converts this field to its `IndexingField` form.
+#
+# @private
+defto_indexing_field
+ to_indexing_field_reference&.resolve
+ end
+
+ # @private
+defresolve_mapping
+ to_indexing_field&.mapping
+ end
+
+ # Returns the string paths to the list fields that we need to index counts for.
+# We do this to support the ability to filter on the size of a list.
+#
+# @private
+defpaths_to_lists_for_count_indexing(has_list_ancestor:false)
+ self_path=(has_list_ancestor||type.list?)?[name_in_index]:[]
+
+ nested_paths=
+ # Nested fields get indexed as separate hidden documents:
+# https://www.elastic.co/guide/en/elasticsearch/reference/8.8/nested.html
+#
+# Given that, the counts of any `nested` list subfields will go in a `__counts` field on the
+# separate hidden document.
+if!nested?&&(object_type=type.fully_unwrapped.as_object_type)
+ object_type.indexing_fields_by_name_in_index.values.flat_mapdo|sub_field|
+ sub_field.paths_to_lists_for_count_indexing(has_list_ancestor:has_list_ancestor||type.list?).mapdo|sub_path|
+ "#{name_in_index}#{LIST_COUNTS_FIELD_PATH_KEY_SEPARATOR}#{sub_path}"
+ end
+ end
+ else
+ []
+ end
+
+ self_path+nested_paths
+ end
+
+ # Indicates if this field is a leaf value in the index. Note that GraphQL leaf values
+# are always leaf values in the index but the inverse is not always true. For example,
+# a `GeoLocation` field is not a leaf in GraphQL (because `GeoLocation` is an object
+# type with subfields) but in the index we use a single `geo_point` mapping type, which
+# is a single unit, so we consider it an index leaf.
+#
+# @private
+defindex_leaf?
+ type_for_derived_types.fully_unwrapped.leaf?||DATASTORE_PROPERTYLESS_OBJECT_TYPES.include?(mapping_type)
+ end
+
+ # @private
+ACCURACY_SCORES={
+ # :high is assigned to `Field`s that are generated directly from GraphQL fields or :extra_fields.
+# For these, we know everything available to us in the schema about them.
+high:3,
+
+ # :medium is assigned to `Field`s that are inferred from the id fields required by a relation.
+# We make logical guesses about the `indexing_field_type` but if the field is also manually defined,
+# it could be slightly different (e.g. additional json schema validations), so we have medium
+# confidence of these.
+medium:2,
+
+ # :low is assigned to the ElastcField inferred for the foreign key of an inbound relation. The
+# nullability/cardinality of the foreign key field cannot be known from the relation metadata,
+# so we just guess what seems safest (`[:nullable]`). If the field is defined another way
+# we should prefer it, so we give these fields :low confidence.
+low:1
+ }
+
+ # Given two fields, picks the one that is most accurate. If they have the same accuracy
+# confidence, yields to a block to force it to deal with the discrepancy, unless the fields
+# are exactly equal (in which case we can return either).
+#
+# @private
+defself.pick_most_accurate_from(field1,field2,to_comparable:->(it){it})
+ returnfield1ifto_comparable.call(field1)==to_comparable.call(field2)
+ yieldiffield1.accuracy_confidence==field2.accuracy_confidence
+ # Array#max_by can return nil (when called on an empty array), but our steep type is non-nil.
+# Since it's not smart enough to realize the non-empty-array-usage of `max_by` won't return nil,
+# we have to cast it to untyped here.
+_=[field1,field2].max_by{|f|ACCURACY_SCORES.fetch(f.accuracy_confidence)}
+ end
+
+ # Indicates if the field uses the `nested` mapping type.
+#
+# @private
+defnested?
+ mapping_type=="nested"
+ end
+
+ # Records the `ComputationDetail` that should be on the `runtime_metadata_graphql_field`.
+#
+# @private
+defruntime_metadata_computation_detail(empty_bucket_value:,function:)
+ self.computation_detail=SchemaArtifacts::RuntimeMetadata::ComputationDetail.new(
+ empty_bucket_value:empty_bucket_value,
+ function:function
+ )
+ end
+
+ # Lazily creates and returns a GraphQLField using the field's {#name_in_index}, {#computation_detail},
+# and {#relationship}.
+#
+# @private
+defruntime_metadata_graphql_field
+ SchemaArtifacts::RuntimeMetadata::GraphQLField.new(
+ name_in_index:name_in_index,
+ computation_detail:computation_detail,
+ relation:relationship&.runtime_metadata
+ )
+ end
+
+ private
+
+ defargs_sdl(joiner:,after_opening_paren:"",&arg_selector)
+ selected_args=args.values.select(&arg_selector)
+ args_sdl=selected_args.map(&:to_sdl).flat_map{|s|s.split("\n")}.join(joiner)
+ returnnilifargs_sdl.empty?
+ "(#{after_opening_paren}#{args_sdl})"
+ end
+
+ # Indicates if the field uses the `text` mapping type.
+deftext?
+ mapping_type=="text"
+ end
+
+ defdefine_legacy_timestamp_grouping_arguments_if_needed(grouping_field)
+ casetype.fully_unwrapped.name
+ when"Date"
+ grouping_field.argumentschema_def_state.schema_elements.granularity,"DateGroupingGranularity!"do|a|
+ a.documentation"Determines the grouping granularity for this field."
+ end
+
+ grouping_field.argumentschema_def_state.schema_elements.offset_days,"Int"do|a|
+ a.documentation<<~EOS
+ Number of days (positive or negative) to shift the `Date` boundaries of each date grouping bucket.
+
+ For example, when grouping by `YEAR`, this can be used to align the buckets with fiscal or school years instead of calendar years.
+ EOS
+end
+ when"DateTime"
+ grouping_field.argumentschema_def_state.schema_elements.granularity,"DateTimeGroupingGranularity!"do|a|
+ a.documentation"Determines the grouping granularity for this field."
+ end
+
+ grouping_field.argumentschema_def_state.schema_elements.time_zone,"TimeZone"do|a|
+ a.documentation"The time zone to use when determining which grouping a `DateTime` value falls in."
+ a.default"UTC"
+ end
+
+ grouping_field.argumentschema_def_state.schema_elements.offset,"DateTimeGroupingOffsetInput"do|a|
+ a.documentation<<~EOS
+ Amount of offset (positive or negative) to shift the `DateTime` boundaries of each grouping bucket.
+
+ For example, when grouping by `WEEK`, you can shift by 24 hours to change what day-of-week weeks are considered to start on.
+ EOS
+end
+ end
+ end
+
+ deflist_field_grouped_by_doc_note(individual_value_selection_description)
+ <<~EOS.strip
+ Note: `#{name}` is a collection field, but selecting this field will group on individual values of #{individual_value_selection_description}.
+ That means that a document may be grouped into multiple aggregation groupings (i.e. when its `#{name}`
+ field has multiple values) leading to some data duplication in the response. However, if a value shows
+ up in `#{name}` multiple times for a single document, that document will only be included in the group
+ once
+ EOS
+end
+
+ # Determines the suffix of the filter field derived for this field. The suffix used determines
+# the filtering capabilities (e.g. filtering on a single value vs a list of values with `any_satisfy`).
+deffilter_field_category(for_single_value)
+ return:filter_inputiffor_single_value
+
+ # For an index leaf field, there are no further nesting paths to traverse. We want to directly
+# use a `ListFilterInput` type (e.g. `IntListFilterInput`) to offer `any_satisfy` filtering at this level.
+return:list_filter_inputifindex_leaf?
+
+ # If it's a list-of-objects field we require the user to tell us what mapping type they want to
+# use, which determines the suffix (and is handled below). Otherwise, we want to use `FieldsListFilterInput`.
+# We are within a list filtering context (as indicated by `for_single_value` being false) without
+# being at an index leaf field, so we must use `FieldsListFilterInput` as there are further nesting paths
+# on the document and we want to provide `any_satisfy` at the leaf fields.
+return:fields_list_filter_inputunlesstype_for_derived_types.list?
+
+ casemapping_type
+ when"nested"then:list_filter_input
+ when"object"then:fields_list_filter_input
+ else
+ raiseErrors::SchemaError,<<~EOS
+ `#{parent_type.name}.#{name}` is a list-of-objects field, but the mapping type has not been explicitly specified. Elasticsearch and OpenSearch
+ offer two ways to index list-of-objects fields. It cannot be changed on an existing field without dropping the index and recreating it (losing
+ any existing indexed data!), and there are nuanced tradeoffs involved here, so ElasticGraph provides no default mapping in this situation.
+
+ If you're currently prototyping and don't want to spend time weighing this tradeoff, we recommend you do this:
+
+ ```
+ t.field "#{name}", "#{type.name}" do |f|
+ # Here we are opting for flexibility (nested) over pure performance (object).
+ # TODO: evaluate if we want to stick with `nested` before going to production.
+ f.mapping type: "nested"
+ end
+ ```
+
+ Read on for details of the tradeoff involved here.
+
+ -----------------------------------------------------------------------------------------------------------------------------
+
+ Here are the options:
+
+ 1) `f.mapping type: "object"` will cause each field path to be indexed as a separate "flattened" list.
+
+ For example, given a `Film` document like this:
+
+ ```
+ {
+ "name": "The Empire Strikes Back",
+ "characters": [
+ {"first": "Luke", "last": "Skywalker"},
+ {"first": "Han", "last": "Solo"}
+ ]
+ }
+ ```
+
+ ...the data will look like this in the inverted Lucene index:
+
+ ```
+ {
+ "name": "The Empire Strikes Back",
+ "characters.first": ["Luke", "Han"],
+ "characters.last": ["Skywalker", "Solo"]
+ }
+ ```
+
+ This is highly efficient, but there is no way to search on multiple fields of a character and be sure that the matching values came from the same character.
+ ElasticGraph models this in the filtering API it offers for this case:
+
+ ```
+ query {
+ films(filter: {
+ characters: {
+ first: {#{schema_def_state.schema_elements.any_satisfy}: {#{schema_def_state.schema_elements.equal_to_any_of}: ["Luke"]}}
+ last: {#{schema_def_state.schema_elements.any_satisfy}: {#{schema_def_state.schema_elements.equal_to_any_of}: ["Skywalker"]}}
+ }
+ }) {
+ # ...
+ }
+ }
+ ```
+
+ As suggested by this filtering API, this will match any film that has a character with a first name of "Luke" and a character
+ with the last name of "Skywalker", but this could be satisfied by two separate characters.
+
+ 2) `f.mapping type: "nested"` will cause each _object_ in the list to be indexed as a separate hidden document, preserving the independence of each.
+
+ Given a `Film` document like "The Empire Strikes Back" from above, the `nested` type will index separate hidden documents for each character. This
+ allows ElasticGraph to offer this filtering API instead:
+
+ ```
+ query {
+ films(filter: {
+ characters: {#{schema_def_state.schema_elements.any_satisfy}: {
+ first: {#{schema_def_state.schema_elements.equal_to_any_of}: ["Luke"]}
+ last: {#{schema_def_state.schema_elements.equal_to_any_of}: ["Skywalker"]}
+ }}
+ }) {
+ # ...
+ }
+ }
+ ```
+
+ As suggested by this filtering API, this will only match films that have a character named "Luke Skywalker". However, the Elasticsearch docs[^1][^2] warn
+ that the `nested` mapping type can lead to performance problems, and index sorting cannot be configured[^3] when the `nested` type is used.
+
+ [^1]: https://www.elastic.co/guide/en/elasticsearch/reference/8.10/nested.html
+ [^2]: https://www.elastic.co/guide/en/elasticsearch/reference/8.10/joining-queries.html
+ [^3]: https://www.elastic.co/guide/en/elasticsearch/reference/8.10/index-modules-index-sorting.html
+ EOS
+end
+ end
+end
+
+
+
+
+
+
+
+
+
+
+ #name_in_index ⇒ String(readonly)
+
+
+
+
+
+
+
+
Returns the name of this field in the datastore index.
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/schema_elements/field.rb', line 89
+
+classField<Struct.new(
+ :name,:original_type,:parent_type,:original_type_for_derived_types,:schema_def_state,:accuracy_confidence,
+ :filter_customizations,:grouped_by_customizations,:sub_aggregations_customizations,
+ :aggregated_values_customizations,:sort_order_enum_value_customizations,
+ :args,:sortable,:filterable,:aggregatable,:groupable,:graphql_only,:source,:runtime_field_script,:relationship,:singular_name,
+ :computation_detail,:non_nullable_in_json_schema,:backing_indexing_field,:as_input,
+ :legacy_grouping_schema,:name_in_index
+)
+ includeMixins::HasDocumentation
+ includeMixins::HasDirectives
+ includeMixins::HasTypeInfo
+ includeMixins::HasReadableToSAndInspect.new{|f|"#{f.parent_type.name}.#{f.name}: #{f.type}"}
+
+ # @private
+definitialize(
+ name:,type:,parent_type:,schema_def_state:,
+ accuracy_confidence::high,name_in_index:name,
+ runtime_metadata_graphql_field:SchemaArtifacts::RuntimeMetadata::GraphQLField::EMPTY,
+ type_for_derived_types:nil,graphql_only:nil,singular:nil,
+ sortable:nil,filterable:nil,aggregatable:nil,groupable:nil,
+ backing_indexing_field:nil,as_input:false,legacy_grouping_schema:false
+ )
+ type_ref=schema_def_state.type_ref(type)
+ super(
+ name:name,
+ original_type:type_ref,
+ parent_type:parent_type,
+ original_type_for_derived_types:type_for_derived_types?schema_def_state.type_ref(type_for_derived_types):type_ref,
+ schema_def_state:schema_def_state,
+ accuracy_confidence:accuracy_confidence,
+ filter_customizations:[],
+ grouped_by_customizations:[],
+ sub_aggregations_customizations:[],
+ aggregated_values_customizations:[],
+ sort_order_enum_value_customizations:[],
+ args:{},
+ sortable:sortable,
+ filterable:filterable,
+ aggregatable:aggregatable,
+ groupable:groupable,
+ graphql_only:graphql_only,
+ source:nil,
+ runtime_field_script:nil,
+ # Note: we named the keyword argument `singular` (with no `_name` suffix) for consistency with
+# other schema definition APIs, which also use `singular:` instead of `singular_name:`. We include
+# the `_name` suffix on the attribute for clarity.
+singular_name:singular,
+ name_in_index:name_in_index,
+ non_nullable_in_json_schema:false,
+ backing_indexing_field:backing_indexing_field,
+ as_input:as_input,
+ legacy_grouping_schema:legacy_grouping_schema
+ )
+
+ ifname!=name_in_index&&name_in_index&.include?(".")&&!graphql_only
+ raiseErrors::SchemaError,"#{self} has an invalid `name_in_index`: #{name_in_index.inspect}. Only `graphql_only: true` fields can have a `name_in_index` that references a child field."
+ end
+
+ schema_def_state.register_user_defined_field(self)
+ yieldselfifblock_given?
+ end
+
+ # @private
+@@initialize_param_names=instance_method(:initialize).parameters.map(&:last).to_set
+
+ # must come after we capture the initialize params.
+prependMixins::VerifiesGraphQLName
+
+ # @return [TypeReference] the type of this field
+deftype
+ # Here we lazily convert the `original_type` to an input type as needed. This must be lazy because
+# the logic of `as_input` depends on detecting whether the type is an enum type, which it may not
+# be able to do right away--we assume not if we can't tell, and retry every time this method is called.
+original_type.to_final_form(as_input:as_input)
+ end
+
+ # @return [TypeReference] the type of the corresponding field on derived types (usually this is the same as {#type}).
+#
+# @private
+deftype_for_derived_types
+ original_type_for_derived_types.to_final_form(as_input:as_input)
+ end
+
+ # @note For each field defined in your schema that is filterable, a corresponding filtering field will be created on the
+# `*FilterInput` type derived from the parent object type.
+#
+# Registers a customization callback that will be applied to the corresponding filtering field that will be generated for this
+# field.
+#
+# @yield [Field] derived filtering field
+# @return [void]
+# @see #customize_aggregated_values_field
+# @see #customize_grouped_by_field
+# @see #customize_sort_order_enum_values
+# @see #customize_sub_aggregations_field
+# @see #on_each_generated_schema_element
+#
+# @example Mark `CampaignFilterInput.organizationId` with `@deprecated`
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Campaign" do |t|
+# t.field "id", "ID"
+#
+# t.field "organizationId", "ID" do |f|
+# f.customize_filter_field do |ff|
+# ff.directive "deprecated"
+# end
+# end
+#
+# t.index "campaigns"
+# end
+# end
+defcustomize_filter_field(&customization_block)
+ filter_customizations<<customization_block
+ end
+
+ # @note For each field defined in your schema that is aggregatable, a corresponding `aggregatedValues` field will be created on the
+# `*AggregatedValues` type derived from the parent object type.
+#
+# Registers a customization callback that will be applied to the corresponding `aggregatedValues` field that will be generated for
+# this field.
+#
+# @yield [Field] derived aggregated values field
+# @return [void]
+# @see #customize_filter_field
+# @see #customize_grouped_by_field
+# @see #customize_sort_order_enum_values
+# @see #customize_sub_aggregations_field
+# @see #on_each_generated_schema_element
+#
+# @example Mark `CampaignAggregatedValues.adImpressions` with `@deprecated`
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Campaign" do |t|
+# t.field "id", "ID"
+#
+# t.field "adImpressions", "Int" do |f|
+# f.customize_aggregated_values_field do |avf|
+# avf.directive "deprecated"
+# end
+# end
+#
+# t.index "campaigns"
+# end
+# end
+defcustomize_aggregated_values_field(&customization_block)
+ aggregated_values_customizations<<customization_block
+ end
+
+ # @note For each field defined in your schema that is groupable, a corresponding `groupedBy` field will be created on the
+# `*AggregationGroupedBy` type derived from the parent object type.
+#
+# Registers a customization callback that will be applied to the corresponding `groupedBy` field that will be generated for this
+# field.
+#
+# @yield [Field] derived grouped by field
+# @return [void]
+# @see #customize_aggregated_values_field
+# @see #customize_filter_field
+# @see #customize_sort_order_enum_values
+# @see #customize_sub_aggregations_field
+# @see #on_each_generated_schema_element
+#
+# @example Mark `CampaignGroupedBy.organizationId` with `@deprecated`
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Campaign" do |t|
+# t.field "id", "ID"
+#
+# t.field "organizationId", "ID" do |f|
+# f.customize_grouped_by_field do |gbf|
+# gbf.directive "deprecated"
+# end
+# end
+#
+# t.index "campaigns"
+# end
+# end
+defcustomize_grouped_by_field(&customization_block)
+ grouped_by_customizations<<customization_block
+ end
+
+ # @note For each field defined in your schema that is sub-aggregatable (e.g. list fields indexed using the `nested` mapping type),
+# a corresponding field will be created on the `*AggregationSubAggregations` type derived from the parent object type.
+#
+# Registers a customization callback that will be applied to the corresponding `subAggregations` field that will be generated for
+# this field.
+#
+# @yield [Field] derived sub-aggregations field
+# @return [void]
+# @see #customize_aggregated_values_field
+# @see #customize_filter_field
+# @see #customize_grouped_by_field
+# @see #customize_sort_order_enum_values
+# @see #on_each_generated_schema_element
+#
+# @example Mark `TransactionAggregationSubAggregations.fees` with `@deprecated`
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Transaction" do |t|
+# t.field "id", "ID"
+#
+# t.field "fees", "[Money!]!" do |f|
+# f.mapping type: "nested"
+#
+# f.customize_sub_aggregations_field do |saf|
+# # Adds a `@deprecated` directive to the `PaymentAggregationSubAggregations.fees`
+# # field without also adding it to the `Payment.fees` field.
+# saf.directive "deprecated"
+# end
+# end
+#
+# t.index "transactions"
+# end
+#
+# schema.object_type "Money" do |t|
+# t.field "amount", "Int"
+# t.field "currency", "String"
+# end
+# end
+defcustomize_sub_aggregations_field(&customization_block)
+ sub_aggregations_customizations<<customization_block
+ end
+
+ # @note for each sortable field, enum values will be generated on the derived sort order enum type allowing you to
+# sort by the field `ASC` or `DESC`.
+#
+# Registers a customization callback that will be applied to the corresponding enum values that will be generated for this field
+# on the derived `SortOrder` enum type.
+#
+# @yield [SortOrderEnumValue] derived sort order enum value
+# @return [void]
+# @see #customize_aggregated_values_field
+# @see #customize_filter_field
+# @see #customize_grouped_by_field
+# @see #customize_sub_aggregations_field
+# @see #on_each_generated_schema_element
+#
+# @example Mark `CampaignSortOrder.organizationId_(ASC|DESC)` with `@deprecated`
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Campaign" do |t|
+# t.field "id", "ID"
+#
+# t.field "organizationId", "ID" do |f|
+# f.customize_sort_order_enum_values do |soev|
+# soev.directive "deprecated"
+# end
+# end
+#
+# t.index "campaigns"
+# end
+# end
+defcustomize_sort_order_enum_values(&customization_block)
+ sort_order_enum_value_customizations<<customization_block
+ end
+
+ # When you define a {Field} on an {ObjectType} or {InterfaceType}, ElasticGraph generates up to 6 different GraphQL schema elements
+# for it:
+#
+# * A {Field} is generated on the parent {ObjectType} or {InterfaceType} (that is, this field itself). This is used by clients to
+# ask for values for the field in a response.
+# * A {Field} may be generated on the `*FilterInput` {InputType} derived from the parent {ObjectType} or {InterfaceType}. This is
+# used by clients to specify how the query should filter.
+# * A {Field} may be generated on the `*AggregationGroupedBy` {ObjectType} derived from the parent {ObjectType} or {InterfaceType}.
+# This is used by clients to specify how aggregations should be grouped.
+# * A {Field} may be generated on the `*AggregatedValues` {ObjectType} derived from the parent {ObjectType} or {InterfaceType}.
+# This is used by clients to apply aggregation functions (e.g. `sum`, `max`, `min`, etc) to a set of field values for a group.
+# * A {Field} may be generated on the `*AggregationSubAggregations` {ObjectType} derived from the parent {ObjectType} or
+# {InterfaceType}. This is used by clients to perform sub-aggregations on list fields indexed using the `nested` mapping type.
+# * Multiple {EnumValue}s (both `*_ASC` and `*_DESC`) are generated on the `*SortOrder` {EnumType} derived from the parent indexed
+# {ObjectType}. This is used by clients to sort by a field.
+#
+# This method registers a customization callback which is applied to every element that is generated for this field.
+#
+# @yield [Field, EnumValue] the schema element
+# @return [void]
+# @see #customize_aggregated_values_field
+# @see #customize_filter_field
+# @see #customize_grouped_by_field
+# @see #customize_sort_order_enum_values
+# @see #customize_sub_aggregations_field
+#
+# @example
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Transaction" do |t|
+# t.field "id", "ID"
+#
+# t.field "amount", "Int" do |f|
+# f.on_each_generated_schema_element do |element|
+# # Adds a `@deprecated` directive to every GraphQL schema element generated for `amount`:
+# #
+# # - The `Transaction.amount` field.
+# # - The `TransactionFilterInput.amount` field.
+# # - The `TransactionAggregationGroupedBy.amount` field.
+# # - The `TransactionAggregatedValues.amount` field.
+# # - The `TransactionSortOrder.amount_ASC` and`TransactionSortOrder.amount_DESC` enum values.
+# element.directive "deprecated"
+# end
+# end
+#
+# t.index "transactions"
+# end
+# end
+defon_each_generated_schema_element(&customization_block)
+ customization_block.call(self)
+ customize_filter_field(&customization_block)
+ customize_aggregated_values_field(&customization_block)
+ customize_grouped_by_field(&customization_block)
+ customize_sub_aggregations_field(&customization_block)
+ customize_sort_order_enum_values(&customization_block)
+ end
+
+ # (see Mixins::HasTypeInfo#json_schema)
+defjson_schema(nullable:nil,**options)
+ ifoptions.key?(:type)
+ raiseErrors::SchemaError,"Cannot override JSON schema type of field `#{name}` with `#{options.fetch(:type)}`"
+ end
+
+ casenullable
+ whentrue
+ raiseErrors::SchemaError,"`nullable: true` is not allowed on a field--just declare the GraphQL field as being nullable (no `!` suffix) instead."
+ whenfalse
+ self.non_nullable_in_json_schema=true
+ end
+
+ super(**options)
+ end
+
+ # Configures ElasticGraph to source a field’s value from a related object. This can be used to denormalize data at ingestion time to
+# support filtering, grouping, sorting, or aggregating data on a field from a related object.
+#
+# @param relationship [String] name of a relationship defined with {TypeWithSubfields#relates_to_one} using an inbound foreign key
+# which contains the the field you wish to source values from
+# @param field_path [String] dot-separated path to the field on the related type containing values that should be copied to this
+# field
+# @return [void]
+#
+# @example Source `City.currency` from `Country.currency`
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Country" do |t|
+# t.field "id", "ID"
+# t.field "name", "String"
+# t.field "currency", "String"
+# t.relates_to_one "capitalCity", "City", via: "capitalCityId", dir: :out
+# t.index "countries"
+# end
+#
+# schema.object_type "City" do |t|
+# t.field "id", "ID"
+# t.field "name", "String"
+# t.relates_to_one "capitalOf", "Country", via: "capitalCityId", dir: :in
+#
+# t.field "currency", "String" do |f|
+# f.sourced_from "capitalOf", "currency"
+# end
+#
+# t.index "cities"
+# end
+# end
+defsourced_from(relationship,field_path)
+ self.source=schema_def_state.factory.new_field_source(
+ relationship_name:relationship,
+ field_path:field_path
+ )
+ end
+
+ # @private
+defruntime_script(script)
+ self.runtime_field_script=script
+ end
+
+ # Registers an old name that this field used to have in a prior version of the schema.
+#
+# @note In situations where this API applies, ElasticGraph will give you an error message indicating that you need to use this API
+# or {TypeWithSubfields#deleted_field}. Likewise, when ElasticGraph no longer needs to know about this, it'll give you a warning
+# indicating the call to this method can be removed.
+#
+# @param old_name [String] old name this field used to have in a prior version of the schema
+# @return [void]
+#
+# @example Indicate that `Widget.description` used to be called `Widget.notes`.
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Widget" do |t|
+# t.field "description", "String" do |f|
+# f.renamed_from "notes"
+# end
+# end
+# end
+defrenamed_from(old_name)
+ schema_def_state.register_renamed_field(
+ parent_type.name,
+ from:old_name,
+ to:name,
+ defined_at:caller_locations(1,1).first,# : ::Thread::Backtrace::Location
+defined_via:%(field.renamed_from "#{old_name}")
+ )
+ end
+
+ # @private
+defto_sdl(type_structure_only:false,default_value_sdl:nil,&arg_selector)
+ iftype_structure_only
+ "#{name}#{args_sdl(joiner:", ",&arg_selector)}: #{type.name}"
+ else
+ args_sdl=args_sdl(joiner:"\n ",after_opening_paren:"\n ",&arg_selector)
+ "#{formatted_documentation}#{name}#{args_sdl}: #{type.name}#{default_value_sdl}#{directives_sdl}".strip
+ end
+ end
+
+ # Indicates if this field is sortable. Sortable fields will have corresponding `_ASC` and `_DESC` values generated in the
+# sort order {EnumType} of the parent indexed type.
+#
+# By default, the sortability is inferred by the field type and mapping. For example, list fields are not sortable,
+# and fields mapped as `text` are not sortable either. Fields are sortable in most other cases.
+#
+# The `sortable: true` option can be used to force a field to be sortable.
+#
+# @return [Boolean] true if this field is sortable
+defsortable?
+ returnsortableunlesssortable.nil?
+
+ # List fields are not sortable by default. We'd need to provide the datastore a sort mode option:
+# https://www.elastic.co/guide/en/elasticsearch/reference/current/sort-search-results.html#_sort_mode_option
+returnfalseiftype.list?
+
+ # Boolean fields are not sortable by default.
+# - Boolean: sorting all falses before all trues (or whatever) is not generally interesting.
+returnfalseiftype.unwrap_non_null.boolean?
+
+ # Elasticsearch/OpenSearch do not support sorting text fields:
+# > Text fields are not used for sorting...
+# (from https://www.elastic.co/guide/en/elasticsearch/reference/current/the datastore.html#text)
+returnfalseiftext?
+
+ # If the type uses custom mapping type we don't know how if the datastore can sort by it, so we assume it's not sortable.
+returnfalseiftype.as_object_type&.has_custom_mapping_type?
+
+ # Default every other field to being sortable.
+true
+ end
+
+ # Indicates if this field is filterable. Filterable fields will be available in the GraphQL schema under the `filter` argument.
+#
+# Most fields are filterable, except when:
+#
+# - It's a relation. Relation fields require us to load the related data from another index and can't be filtered on.
+# - The field is an object type that isn't itself filterable (e.g. due to having no filterable fields or whatever).
+# - Explicitly disabled with `filterable: false`.
+#
+# @return [Boolean]
+deffilterable?
+ # Object types that use custom index mappings (as `GeoLocation` does) aren't filterable
+# by default since we can't guess what datastore filtering capabilities they have. We've implemented
+# filtering support for `GeoLocation` fields, though, so we need to explicitly make it fliterable here.
+# TODO: clean this up using an interface instead of checking for `GeoLocation`.
+returntrueiftype.fully_unwrapped.name=="GeoLocation"
+
+ returnfalseifrelationship||type.fully_unwrapped.as_object_type&.does_not_support?(&:filterable?)
+ returntrueiffilterable.nil?
+ filterable
+ end
+
+ # Indicates if this field is groupable. Groupable fields will be available under `groupedBy` for an aggregations query.
+#
+# Groupability is inferred based on the field type and mapping type, or you can use the `groupable: true` option to force it.
+#
+# @return [Boolean]
+defgroupable?
+ # If the groupability of the field was specified explicitly when the field was defined, use the specified value.
+returngroupableunlessgroupable.nil?
+
+ # We don't want the `id` field of an indexed type to be available to group by, because it's the unique primary key
+# and the groupings would each contain one document. It's simpler and more efficient to just query the raw documents
+# instead.
+returnfalseifparent_type.indexed?&&name=="id"
+
+ returnfalseifrelationship||type.fully_unwrapped.as_object_type&.does_not_support?(&:groupable?)
+
+ # We don't support grouping an entire list of values, but we do support grouping on individual values in a list.
+# However, we only do so when a `singular_name` has been provided (so that we know what to call the grouped_by field).
+# The semantics are a little odd (since one document can be duplicated in multiple grouping buckets) so we're ok
+# with not offering it by default--the user has to opt-in by telling us what to call the field in its singular form.
+returnlist_field_groupable_by_single_values?iftype.list?&&type.fully_unwrapped.leaf?
+
+ # Nested fields will be supported through specific nested aggregation support, and do not
+# work as expected when grouping on the root document type.
+returnfalseifnested?
+
+ # Text fields cannot be efficiently grouped on, so make them non-groupable by default.
+returnfalseiftext?
+
+ # In all other cases, default to being groupable.
+true
+ end
+
+ # Indicates if this field is aggregatable. Aggregatable fields will be available under `aggregatedValues` for an aggregations query.
+#
+# Aggregatability is inferred based on the field type and mapping type, or you can use the `aggregatable: true` option to force it.
+#
+# @return [Boolean]
+defaggregatable?
+ returnaggregatableunlessaggregatable.nil?
+ returnfalseifrelationship
+
+ # We don't yet support aggregating over subfields of a `nested` field.
+# TODO: add support for aggregating over subfields of `nested` fields.
+returnfalseifnested?
+
+ # Text fields are not efficiently aggregatable (and you'll often get errors from the datastore if you attempt to aggregate them).
+returnfalseiftext?
+
+ type_for_derived_types.fully_unwrapped.as_object_type&.supports?(&:aggregatable?)||index_leaf?
+ end
+
+ # Indicates if this field can be used as the basis for a sub-aggregation. Sub-aggregatable fields will be available under
+# `subAggregations` for an aggregations query.
+#
+# Only nested fields, and object fields which have nested fields, can be sub-aggregated.
+#
+# @return [Boolean]
+defsub_aggregatable?
+ returnfalseifrelationship
+
+ nested?||type_for_derived_types.fully_unwrapped.as_object_type&.supports?(&:sub_aggregatable?)
+ end
+
+ # Defines an argument on the field.
+#
+# @note ElasticGraph takes care of defining arguments for all the query features it supports, so there is generally no need to use
+# this API, and it has no way to interpret arbitrary arguments defined on a field. However, it can be useful for extensions that
+# extend the {ElasticGraph::GraphQL} query engine. For example, {ElasticGraph::Apollo} uses this API to satisfy the [Apollo
+# federation subgraph spec](https://www.apollographql.com/docs/federation/federation-spec/).
+#
+# @param name [String] name of the argument
+# @param value_type [String] type of the argument in GraphQL SDL syntax
+# @yield [Argument] for further customization
+#
+# @example Define an argument on a field
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Product" do |t|
+# t.field "name", "String" do |f|
+# f.argument "language", "String"
+# end
+# end
+# end
+defargument(name,value_type,&block)
+ args[name]=schema_def_state.factory.new_argument(
+ self,
+ name,
+ schema_def_state.type_ref(value_type),
+ &block
+ )
+ end
+
+ # The index mapping type in effect for this field. This could come from either the field definition or from the type definition.
+#
+# @return [String]
+defmapping_type
+ backing_indexing_field&.mapping_type||(resolve_mapping||{})["type"]
+ end
+
+ # @private
+deflist_field_groupable_by_single_values?
+ (type.list?||backing_indexing_field&.type&.list?)&&!singular_name.nil?
+ end
+
+ # @private
+defdefine_aggregated_values_field(parent_type)
+ returnunlessaggregatable?
+
+ unwrapped_type_for_derived_types=type_for_derived_types.fully_unwrapped
+ aggregated_values_type=
+ ifindex_leaf?
+ unwrapped_type_for_derived_types.resolved.aggregated_values_type
+ else
+ unwrapped_type_for_derived_types.as_aggregated_values
+ end
+
+ parent_type.fieldname,aggregated_values_type.name,name_in_index:name_in_index,graphql_only:truedo|f|
+ f.documentationderived_documentation("Computed aggregate values for the `#{name}` field")
+ aggregated_values_customizations.each{|block|block.call(f)}
+ end
+ end
+
+ # @private
+defdefine_grouped_by_field(parent_type)
+ returnunless(field_name=grouped_by_field_name)
+
+ parent_type.fieldfield_name,grouped_by_field_type_name,name_in_index:name_in_index,graphql_only:truedo|f|
+ add_grouped_by_field_documentation(f)
+
+ define_legacy_timestamp_grouping_arguments_if_needed(f)iflegacy_grouping_schema
+
+ grouped_by_customizations.each{|block|block.call(f)}
+ end
+ end
+
+ # @private
+defgrouped_by_field_type_name
+ unwrapped_type=type_for_derived_types.fully_unwrapped
+ ifunwrapped_type.scalar_type_needing_grouped_by_object?&&!legacy_grouping_schema
+ unwrapped_type.with_reverted_override.as_grouped_by.name
+ elsifunwrapped_type.leaf?
+ unwrapped_type.name
+ else
+ unwrapped_type.as_grouped_by.name
+ end
+ end
+
+ # @private
+defadd_grouped_by_field_documentation(field)
+ text=iflist_field_groupable_by_single_values?
+ derived_documentation(
+ "The individual value from `#{name}` for this group",
+ list_field_grouped_by_doc_note("`#{name}`")
+ )
+ elsiftype.list?&&type.fully_unwrapped.object?
+ derived_documentation(
+ "The `#{name}` field value for this group",
+ list_field_grouped_by_doc_note("the selected subfields of `#{name}`")
+ )
+ elsiftype_for_derived_types.fully_unwrapped.scalar_type_needing_grouped_by_object?&&!legacy_grouping_schema
+ derived_documentation("Offers the different grouping options for the `#{name}` value within this group")
+ else
+ derived_documentation("The `#{name}` field value for this group")
+ end
+
+ field.documentationtext
+ end
+
+ # @private
+defgrouped_by_field_name
+ returnnilunlessgroupable?
+ list_field_groupable_by_single_values??singular_name:name
+ end
+
+ # @private
+defdefine_sub_aggregations_field(parent_type:,type:)
+ parent_type.fieldname,type,name_in_index:name_in_index,graphql_only:truedo|f|
+ f.documentationderived_documentation("Used to perform a sub-aggregation of `#{name}`")
+ sub_aggregations_customizations.each{|c|c.call(f)}
+
+ yieldfifblock_given?
+ end
+ end
+
+ # @private
+defto_filter_field(parent_type:,for_single_value:!type_for_derived_types.list?)
+ type_prefix=text??"Text":type_for_derived_types.fully_unwrapped.name
+ filter_type=schema_def_state
+ .type_ref(type_prefix)
+ .as_static_derived_type(filter_field_category(for_single_value))
+ .name
+
+ params=to_h
+ .slice(*@@initialize_param_names)
+ .merge(type:filter_type,parent_type:parent_type,name_in_index:name_in_index,type_for_derived_types:nil)
+
+ schema_def_state.factory.new_field(**params).tapdo|f|
+ f.documentationderived_documentation(
+ "Used to filter on the `#{name}` field",
+ "Will be ignored if `null` or an empty object is passed"
+ )
+
+ filter_customizations.each{|c|c.call(f)}
+ end
+ end
+
+ # @private
+defdefine_relay_pagination_arguments!
+ argumentschema_def_state.schema_elements.first.to_sym,"Int"do|a|
+ a.documentation<<~EOS
+ Used in conjunction with the `after` argument to forward-paginate through the `#{name}`.
+ When provided, limits the number of returned results to the first `n` after the provided
+ `after` cursor (or from the start of the `#{name}`, if no `after` cursor is provided).
+
+ See the [Relay GraphQL Cursor Connections
+ Specification](https://relay.dev/graphql/connections.htm#sec-Arguments) for more info.
+ EOS
+end
+
+ argumentschema_def_state.schema_elements.after.to_sym,"Cursor"do|a|
+ a.documentation<<~EOS
+ Used to forward-paginate through the `#{name}`. When provided, the next page after the
+ provided cursor will be returned.
+
+ See the [Relay GraphQL Cursor Connections
+ Specification](https://relay.dev/graphql/connections.htm#sec-Arguments) for more info.
+ EOS
+end
+
+ argumentschema_def_state.schema_elements.last.to_sym,"Int"do|a|
+ a.documentation<<~EOS
+ Used in conjunction with the `before` argument to backward-paginate through the `#{name}`.
+ When provided, limits the number of returned results to the last `n` before the provided
+ `before` cursor (or from the end of the `#{name}`, if no `before` cursor is provided).
+
+ See the [Relay GraphQL Cursor Connections
+ Specification](https://relay.dev/graphql/connections.htm#sec-Arguments) for more info.
+ EOS
+end
+
+ argumentschema_def_state.schema_elements.before.to_sym,"Cursor"do|a|
+ a.documentation<<~EOS
+ Used to backward-paginate through the `#{name}`. When provided, the previous page before the
+ provided cursor will be returned.
+
+ See the [Relay GraphQL Cursor Connections
+ Specification](https://relay.dev/graphql/connections.htm#sec-Arguments) for more info.
+ EOS
+end
+ end
+
+ # Converts this field to an `Indexing::FieldReference`, which contains all the attributes involved
+# in building an `Indexing::Field`. Notably, we cannot actually convert to an `Indexing::Field` at
+# the point this method is called, because the referenced field type may not have been defined
+# yet. We don't need an actual `Indexing::Field` until the very end of the schema definition process,
+# when we are dumping the artifacts. However, we need this at field definition time so that we
+# can correctly detect duplicate indexing field issues when a field is defined. (This is used
+# in `TypeWithSubfields#field`).
+#
+# @private
+defto_indexing_field_reference
+ returnnilifgraphql_only
+
+ Indexing::FieldReference.new(
+ name:name,
+ name_in_index:name_in_index,
+ type:non_nullable_in_json_schema?type.wrap_non_null:type,
+ mapping_options:mapping_options,
+ json_schema_options:json_schema_options,
+ accuracy_confidence:accuracy_confidence,
+ source:source,
+ runtime_field_script:runtime_field_script
+ )
+ end
+
+ # Converts this field to its `IndexingField` form.
+#
+# @private
+defto_indexing_field
+ to_indexing_field_reference&.resolve
+ end
+
+ # @private
+defresolve_mapping
+ to_indexing_field&.mapping
+ end
+
+ # Returns the string paths to the list fields that we need to index counts for.
+# We do this to support the ability to filter on the size of a list.
+#
+# @private
+defpaths_to_lists_for_count_indexing(has_list_ancestor:false)
+ self_path=(has_list_ancestor||type.list?)?[name_in_index]:[]
+
+ nested_paths=
+ # Nested fields get indexed as separate hidden documents:
+# https://www.elastic.co/guide/en/elasticsearch/reference/8.8/nested.html
+#
+# Given that, the counts of any `nested` list subfields will go in a `__counts` field on the
+# separate hidden document.
+if!nested?&&(object_type=type.fully_unwrapped.as_object_type)
+ object_type.indexing_fields_by_name_in_index.values.flat_mapdo|sub_field|
+ sub_field.paths_to_lists_for_count_indexing(has_list_ancestor:has_list_ancestor||type.list?).mapdo|sub_path|
+ "#{name_in_index}#{LIST_COUNTS_FIELD_PATH_KEY_SEPARATOR}#{sub_path}"
+ end
+ end
+ else
+ []
+ end
+
+ self_path+nested_paths
+ end
+
+ # Indicates if this field is a leaf value in the index. Note that GraphQL leaf values
+# are always leaf values in the index but the inverse is not always true. For example,
+# a `GeoLocation` field is not a leaf in GraphQL (because `GeoLocation` is an object
+# type with subfields) but in the index we use a single `geo_point` mapping type, which
+# is a single unit, so we consider it an index leaf.
+#
+# @private
+defindex_leaf?
+ type_for_derived_types.fully_unwrapped.leaf?||DATASTORE_PROPERTYLESS_OBJECT_TYPES.include?(mapping_type)
+ end
+
+ # @private
+ACCURACY_SCORES={
+ # :high is assigned to `Field`s that are generated directly from GraphQL fields or :extra_fields.
+# For these, we know everything available to us in the schema about them.
+high:3,
+
+ # :medium is assigned to `Field`s that are inferred from the id fields required by a relation.
+# We make logical guesses about the `indexing_field_type` but if the field is also manually defined,
+# it could be slightly different (e.g. additional json schema validations), so we have medium
+# confidence of these.
+medium:2,
+
+ # :low is assigned to the ElastcField inferred for the foreign key of an inbound relation. The
+# nullability/cardinality of the foreign key field cannot be known from the relation metadata,
+# so we just guess what seems safest (`[:nullable]`). If the field is defined another way
+# we should prefer it, so we give these fields :low confidence.
+low:1
+ }
+
+ # Given two fields, picks the one that is most accurate. If they have the same accuracy
+# confidence, yields to a block to force it to deal with the discrepancy, unless the fields
+# are exactly equal (in which case we can return either).
+#
+# @private
+defself.pick_most_accurate_from(field1,field2,to_comparable:->(it){it})
+ returnfield1ifto_comparable.call(field1)==to_comparable.call(field2)
+ yieldiffield1.accuracy_confidence==field2.accuracy_confidence
+ # Array#max_by can return nil (when called on an empty array), but our steep type is non-nil.
+# Since it's not smart enough to realize the non-empty-array-usage of `max_by` won't return nil,
+# we have to cast it to untyped here.
+_=[field1,field2].max_by{|f|ACCURACY_SCORES.fetch(f.accuracy_confidence)}
+ end
+
+ # Indicates if the field uses the `nested` mapping type.
+#
+# @private
+defnested?
+ mapping_type=="nested"
+ end
+
+ # Records the `ComputationDetail` that should be on the `runtime_metadata_graphql_field`.
+#
+# @private
+defruntime_metadata_computation_detail(empty_bucket_value:,function:)
+ self.computation_detail=SchemaArtifacts::RuntimeMetadata::ComputationDetail.new(
+ empty_bucket_value:empty_bucket_value,
+ function:function
+ )
+ end
+
+ # Lazily creates and returns a GraphQLField using the field's {#name_in_index}, {#computation_detail},
+# and {#relationship}.
+#
+# @private
+defruntime_metadata_graphql_field
+ SchemaArtifacts::RuntimeMetadata::GraphQLField.new(
+ name_in_index:name_in_index,
+ computation_detail:computation_detail,
+ relation:relationship&.runtime_metadata
+ )
+ end
+
+ private
+
+ defargs_sdl(joiner:,after_opening_paren:"",&arg_selector)
+ selected_args=args.values.select(&arg_selector)
+ args_sdl=selected_args.map(&:to_sdl).flat_map{|s|s.split("\n")}.join(joiner)
+ returnnilifargs_sdl.empty?
+ "(#{after_opening_paren}#{args_sdl})"
+ end
+
+ # Indicates if the field uses the `text` mapping type.
+deftext?
+ mapping_type=="text"
+ end
+
+ defdefine_legacy_timestamp_grouping_arguments_if_needed(grouping_field)
+ casetype.fully_unwrapped.name
+ when"Date"
+ grouping_field.argumentschema_def_state.schema_elements.granularity,"DateGroupingGranularity!"do|a|
+ a.documentation"Determines the grouping granularity for this field."
+ end
+
+ grouping_field.argumentschema_def_state.schema_elements.offset_days,"Int"do|a|
+ a.documentation<<~EOS
+ Number of days (positive or negative) to shift the `Date` boundaries of each date grouping bucket.
+
+ For example, when grouping by `YEAR`, this can be used to align the buckets with fiscal or school years instead of calendar years.
+ EOS
+end
+ when"DateTime"
+ grouping_field.argumentschema_def_state.schema_elements.granularity,"DateTimeGroupingGranularity!"do|a|
+ a.documentation"Determines the grouping granularity for this field."
+ end
+
+ grouping_field.argumentschema_def_state.schema_elements.time_zone,"TimeZone"do|a|
+ a.documentation"The time zone to use when determining which grouping a `DateTime` value falls in."
+ a.default"UTC"
+ end
+
+ grouping_field.argumentschema_def_state.schema_elements.offset,"DateTimeGroupingOffsetInput"do|a|
+ a.documentation<<~EOS
+ Amount of offset (positive or negative) to shift the `DateTime` boundaries of each grouping bucket.
+
+ For example, when grouping by `WEEK`, you can shift by 24 hours to change what day-of-week weeks are considered to start on.
+ EOS
+end
+ end
+ end
+
+ deflist_field_grouped_by_doc_note(individual_value_selection_description)
+ <<~EOS.strip
+ Note: `#{name}` is a collection field, but selecting this field will group on individual values of #{individual_value_selection_description}.
+ That means that a document may be grouped into multiple aggregation groupings (i.e. when its `#{name}`
+ field has multiple values) leading to some data duplication in the response. However, if a value shows
+ up in `#{name}` multiple times for a single document, that document will only be included in the group
+ once
+ EOS
+end
+
+ # Determines the suffix of the filter field derived for this field. The suffix used determines
+# the filtering capabilities (e.g. filtering on a single value vs a list of values with `any_satisfy`).
+deffilter_field_category(for_single_value)
+ return:filter_inputiffor_single_value
+
+ # For an index leaf field, there are no further nesting paths to traverse. We want to directly
+# use a `ListFilterInput` type (e.g. `IntListFilterInput`) to offer `any_satisfy` filtering at this level.
+return:list_filter_inputifindex_leaf?
+
+ # If it's a list-of-objects field we require the user to tell us what mapping type they want to
+# use, which determines the suffix (and is handled below). Otherwise, we want to use `FieldsListFilterInput`.
+# We are within a list filtering context (as indicated by `for_single_value` being false) without
+# being at an index leaf field, so we must use `FieldsListFilterInput` as there are further nesting paths
+# on the document and we want to provide `any_satisfy` at the leaf fields.
+return:fields_list_filter_inputunlesstype_for_derived_types.list?
+
+ casemapping_type
+ when"nested"then:list_filter_input
+ when"object"then:fields_list_filter_input
+ else
+ raiseErrors::SchemaError,<<~EOS
+ `#{parent_type.name}.#{name}` is a list-of-objects field, but the mapping type has not been explicitly specified. Elasticsearch and OpenSearch
+ offer two ways to index list-of-objects fields. It cannot be changed on an existing field without dropping the index and recreating it (losing
+ any existing indexed data!), and there are nuanced tradeoffs involved here, so ElasticGraph provides no default mapping in this situation.
+
+ If you're currently prototyping and don't want to spend time weighing this tradeoff, we recommend you do this:
+
+ ```
+ t.field "#{name}", "#{type.name}" do |f|
+ # Here we are opting for flexibility (nested) over pure performance (object).
+ # TODO: evaluate if we want to stick with `nested` before going to production.
+ f.mapping type: "nested"
+ end
+ ```
+
+ Read on for details of the tradeoff involved here.
+
+ -----------------------------------------------------------------------------------------------------------------------------
+
+ Here are the options:
+
+ 1) `f.mapping type: "object"` will cause each field path to be indexed as a separate "flattened" list.
+
+ For example, given a `Film` document like this:
+
+ ```
+ {
+ "name": "The Empire Strikes Back",
+ "characters": [
+ {"first": "Luke", "last": "Skywalker"},
+ {"first": "Han", "last": "Solo"}
+ ]
+ }
+ ```
+
+ ...the data will look like this in the inverted Lucene index:
+
+ ```
+ {
+ "name": "The Empire Strikes Back",
+ "characters.first": ["Luke", "Han"],
+ "characters.last": ["Skywalker", "Solo"]
+ }
+ ```
+
+ This is highly efficient, but there is no way to search on multiple fields of a character and be sure that the matching values came from the same character.
+ ElasticGraph models this in the filtering API it offers for this case:
+
+ ```
+ query {
+ films(filter: {
+ characters: {
+ first: {#{schema_def_state.schema_elements.any_satisfy}: {#{schema_def_state.schema_elements.equal_to_any_of}: ["Luke"]}}
+ last: {#{schema_def_state.schema_elements.any_satisfy}: {#{schema_def_state.schema_elements.equal_to_any_of}: ["Skywalker"]}}
+ }
+ }) {
+ # ...
+ }
+ }
+ ```
+
+ As suggested by this filtering API, this will match any film that has a character with a first name of "Luke" and a character
+ with the last name of "Skywalker", but this could be satisfied by two separate characters.
+
+ 2) `f.mapping type: "nested"` will cause each _object_ in the list to be indexed as a separate hidden document, preserving the independence of each.
+
+ Given a `Film` document like "The Empire Strikes Back" from above, the `nested` type will index separate hidden documents for each character. This
+ allows ElasticGraph to offer this filtering API instead:
+
+ ```
+ query {
+ films(filter: {
+ characters: {#{schema_def_state.schema_elements.any_satisfy}: {
+ first: {#{schema_def_state.schema_elements.equal_to_any_of}: ["Luke"]}
+ last: {#{schema_def_state.schema_elements.equal_to_any_of}: ["Skywalker"]}
+ }}
+ }) {
+ # ...
+ }
+ }
+ ```
+
+ As suggested by this filtering API, this will only match films that have a character named "Luke Skywalker". However, the Elasticsearch docs[^1][^2] warn
+ that the `nested` mapping type can lead to performance problems, and index sorting cannot be configured[^3] when the `nested` type is used.
+
+ [^1]: https://www.elastic.co/guide/en/elasticsearch/reference/8.10/nested.html
+ [^2]: https://www.elastic.co/guide/en/elasticsearch/reference/8.10/joining-queries.html
+ [^3]: https://www.elastic.co/guide/en/elasticsearch/reference/8.10/index-modules-index-sorting.html
+ EOS
+end
+ end
+end
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/schema_elements/field.rb', line 89
+
+classField<Struct.new(
+ :name,:original_type,:parent_type,:original_type_for_derived_types,:schema_def_state,:accuracy_confidence,
+ :filter_customizations,:grouped_by_customizations,:sub_aggregations_customizations,
+ :aggregated_values_customizations,:sort_order_enum_value_customizations,
+ :args,:sortable,:filterable,:aggregatable,:groupable,:graphql_only,:source,:runtime_field_script,:relationship,:singular_name,
+ :computation_detail,:non_nullable_in_json_schema,:backing_indexing_field,:as_input,
+ :legacy_grouping_schema,:name_in_index
+)
+ includeMixins::HasDocumentation
+ includeMixins::HasDirectives
+ includeMixins::HasTypeInfo
+ includeMixins::HasReadableToSAndInspect.new{|f|"#{f.parent_type.name}.#{f.name}: #{f.type}"}
+
+ # @private
+definitialize(
+ name:,type:,parent_type:,schema_def_state:,
+ accuracy_confidence::high,name_in_index:name,
+ runtime_metadata_graphql_field:SchemaArtifacts::RuntimeMetadata::GraphQLField::EMPTY,
+ type_for_derived_types:nil,graphql_only:nil,singular:nil,
+ sortable:nil,filterable:nil,aggregatable:nil,groupable:nil,
+ backing_indexing_field:nil,as_input:false,legacy_grouping_schema:false
+ )
+ type_ref=schema_def_state.type_ref(type)
+ super(
+ name:name,
+ original_type:type_ref,
+ parent_type:parent_type,
+ original_type_for_derived_types:type_for_derived_types?schema_def_state.type_ref(type_for_derived_types):type_ref,
+ schema_def_state:schema_def_state,
+ accuracy_confidence:accuracy_confidence,
+ filter_customizations:[],
+ grouped_by_customizations:[],
+ sub_aggregations_customizations:[],
+ aggregated_values_customizations:[],
+ sort_order_enum_value_customizations:[],
+ args:{},
+ sortable:sortable,
+ filterable:filterable,
+ aggregatable:aggregatable,
+ groupable:groupable,
+ graphql_only:graphql_only,
+ source:nil,
+ runtime_field_script:nil,
+ # Note: we named the keyword argument `singular` (with no `_name` suffix) for consistency with
+# other schema definition APIs, which also use `singular:` instead of `singular_name:`. We include
+# the `_name` suffix on the attribute for clarity.
+singular_name:singular,
+ name_in_index:name_in_index,
+ non_nullable_in_json_schema:false,
+ backing_indexing_field:backing_indexing_field,
+ as_input:as_input,
+ legacy_grouping_schema:legacy_grouping_schema
+ )
+
+ ifname!=name_in_index&&name_in_index&.include?(".")&&!graphql_only
+ raiseErrors::SchemaError,"#{self} has an invalid `name_in_index`: #{name_in_index.inspect}. Only `graphql_only: true` fields can have a `name_in_index` that references a child field."
+ end
+
+ schema_def_state.register_user_defined_field(self)
+ yieldselfifblock_given?
+ end
+
+ # @private
+@@initialize_param_names=instance_method(:initialize).parameters.map(&:last).to_set
+
+ # must come after we capture the initialize params.
+prependMixins::VerifiesGraphQLName
+
+ # @return [TypeReference] the type of this field
+deftype
+ # Here we lazily convert the `original_type` to an input type as needed. This must be lazy because
+# the logic of `as_input` depends on detecting whether the type is an enum type, which it may not
+# be able to do right away--we assume not if we can't tell, and retry every time this method is called.
+original_type.to_final_form(as_input:as_input)
+ end
+
+ # @return [TypeReference] the type of the corresponding field on derived types (usually this is the same as {#type}).
+#
+# @private
+deftype_for_derived_types
+ original_type_for_derived_types.to_final_form(as_input:as_input)
+ end
+
+ # @note For each field defined in your schema that is filterable, a corresponding filtering field will be created on the
+# `*FilterInput` type derived from the parent object type.
+#
+# Registers a customization callback that will be applied to the corresponding filtering field that will be generated for this
+# field.
+#
+# @yield [Field] derived filtering field
+# @return [void]
+# @see #customize_aggregated_values_field
+# @see #customize_grouped_by_field
+# @see #customize_sort_order_enum_values
+# @see #customize_sub_aggregations_field
+# @see #on_each_generated_schema_element
+#
+# @example Mark `CampaignFilterInput.organizationId` with `@deprecated`
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Campaign" do |t|
+# t.field "id", "ID"
+#
+# t.field "organizationId", "ID" do |f|
+# f.customize_filter_field do |ff|
+# ff.directive "deprecated"
+# end
+# end
+#
+# t.index "campaigns"
+# end
+# end
+defcustomize_filter_field(&customization_block)
+ filter_customizations<<customization_block
+ end
+
+ # @note For each field defined in your schema that is aggregatable, a corresponding `aggregatedValues` field will be created on the
+# `*AggregatedValues` type derived from the parent object type.
+#
+# Registers a customization callback that will be applied to the corresponding `aggregatedValues` field that will be generated for
+# this field.
+#
+# @yield [Field] derived aggregated values field
+# @return [void]
+# @see #customize_filter_field
+# @see #customize_grouped_by_field
+# @see #customize_sort_order_enum_values
+# @see #customize_sub_aggregations_field
+# @see #on_each_generated_schema_element
+#
+# @example Mark `CampaignAggregatedValues.adImpressions` with `@deprecated`
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Campaign" do |t|
+# t.field "id", "ID"
+#
+# t.field "adImpressions", "Int" do |f|
+# f.customize_aggregated_values_field do |avf|
+# avf.directive "deprecated"
+# end
+# end
+#
+# t.index "campaigns"
+# end
+# end
+defcustomize_aggregated_values_field(&customization_block)
+ aggregated_values_customizations<<customization_block
+ end
+
+ # @note For each field defined in your schema that is groupable, a corresponding `groupedBy` field will be created on the
+# `*AggregationGroupedBy` type derived from the parent object type.
+#
+# Registers a customization callback that will be applied to the corresponding `groupedBy` field that will be generated for this
+# field.
+#
+# @yield [Field] derived grouped by field
+# @return [void]
+# @see #customize_aggregated_values_field
+# @see #customize_filter_field
+# @see #customize_sort_order_enum_values
+# @see #customize_sub_aggregations_field
+# @see #on_each_generated_schema_element
+#
+# @example Mark `CampaignGroupedBy.organizationId` with `@deprecated`
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Campaign" do |t|
+# t.field "id", "ID"
+#
+# t.field "organizationId", "ID" do |f|
+# f.customize_grouped_by_field do |gbf|
+# gbf.directive "deprecated"
+# end
+# end
+#
+# t.index "campaigns"
+# end
+# end
+defcustomize_grouped_by_field(&customization_block)
+ grouped_by_customizations<<customization_block
+ end
+
+ # @note For each field defined in your schema that is sub-aggregatable (e.g. list fields indexed using the `nested` mapping type),
+# a corresponding field will be created on the `*AggregationSubAggregations` type derived from the parent object type.
+#
+# Registers a customization callback that will be applied to the corresponding `subAggregations` field that will be generated for
+# this field.
+#
+# @yield [Field] derived sub-aggregations field
+# @return [void]
+# @see #customize_aggregated_values_field
+# @see #customize_filter_field
+# @see #customize_grouped_by_field
+# @see #customize_sort_order_enum_values
+# @see #on_each_generated_schema_element
+#
+# @example Mark `TransactionAggregationSubAggregations.fees` with `@deprecated`
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Transaction" do |t|
+# t.field "id", "ID"
+#
+# t.field "fees", "[Money!]!" do |f|
+# f.mapping type: "nested"
+#
+# f.customize_sub_aggregations_field do |saf|
+# # Adds a `@deprecated` directive to the `PaymentAggregationSubAggregations.fees`
+# # field without also adding it to the `Payment.fees` field.
+# saf.directive "deprecated"
+# end
+# end
+#
+# t.index "transactions"
+# end
+#
+# schema.object_type "Money" do |t|
+# t.field "amount", "Int"
+# t.field "currency", "String"
+# end
+# end
+defcustomize_sub_aggregations_field(&customization_block)
+ sub_aggregations_customizations<<customization_block
+ end
+
+ # @note for each sortable field, enum values will be generated on the derived sort order enum type allowing you to
+# sort by the field `ASC` or `DESC`.
+#
+# Registers a customization callback that will be applied to the corresponding enum values that will be generated for this field
+# on the derived `SortOrder` enum type.
+#
+# @yield [SortOrderEnumValue] derived sort order enum value
+# @return [void]
+# @see #customize_aggregated_values_field
+# @see #customize_filter_field
+# @see #customize_grouped_by_field
+# @see #customize_sub_aggregations_field
+# @see #on_each_generated_schema_element
+#
+# @example Mark `CampaignSortOrder.organizationId_(ASC|DESC)` with `@deprecated`
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Campaign" do |t|
+# t.field "id", "ID"
+#
+# t.field "organizationId", "ID" do |f|
+# f.customize_sort_order_enum_values do |soev|
+# soev.directive "deprecated"
+# end
+# end
+#
+# t.index "campaigns"
+# end
+# end
+defcustomize_sort_order_enum_values(&customization_block)
+ sort_order_enum_value_customizations<<customization_block
+ end
+
+ # When you define a {Field} on an {ObjectType} or {InterfaceType}, ElasticGraph generates up to 6 different GraphQL schema elements
+# for it:
+#
+# * A {Field} is generated on the parent {ObjectType} or {InterfaceType} (that is, this field itself). This is used by clients to
+# ask for values for the field in a response.
+# * A {Field} may be generated on the `*FilterInput` {InputType} derived from the parent {ObjectType} or {InterfaceType}. This is
+# used by clients to specify how the query should filter.
+# * A {Field} may be generated on the `*AggregationGroupedBy` {ObjectType} derived from the parent {ObjectType} or {InterfaceType}.
+# This is used by clients to specify how aggregations should be grouped.
+# * A {Field} may be generated on the `*AggregatedValues` {ObjectType} derived from the parent {ObjectType} or {InterfaceType}.
+# This is used by clients to apply aggregation functions (e.g. `sum`, `max`, `min`, etc) to a set of field values for a group.
+# * A {Field} may be generated on the `*AggregationSubAggregations` {ObjectType} derived from the parent {ObjectType} or
+# {InterfaceType}. This is used by clients to perform sub-aggregations on list fields indexed using the `nested` mapping type.
+# * Multiple {EnumValue}s (both `*_ASC` and `*_DESC`) are generated on the `*SortOrder` {EnumType} derived from the parent indexed
+# {ObjectType}. This is used by clients to sort by a field.
+#
+# This method registers a customization callback which is applied to every element that is generated for this field.
+#
+# @yield [Field, EnumValue] the schema element
+# @return [void]
+# @see #customize_aggregated_values_field
+# @see #customize_filter_field
+# @see #customize_grouped_by_field
+# @see #customize_sort_order_enum_values
+# @see #customize_sub_aggregations_field
+#
+# @example
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Transaction" do |t|
+# t.field "id", "ID"
+#
+# t.field "amount", "Int" do |f|
+# f.on_each_generated_schema_element do |element|
+# # Adds a `@deprecated` directive to every GraphQL schema element generated for `amount`:
+# #
+# # - The `Transaction.amount` field.
+# # - The `TransactionFilterInput.amount` field.
+# # - The `TransactionAggregationGroupedBy.amount` field.
+# # - The `TransactionAggregatedValues.amount` field.
+# # - The `TransactionSortOrder.amount_ASC` and`TransactionSortOrder.amount_DESC` enum values.
+# element.directive "deprecated"
+# end
+# end
+#
+# t.index "transactions"
+# end
+# end
+defon_each_generated_schema_element(&customization_block)
+ customization_block.call(self)
+ customize_filter_field(&customization_block)
+ customize_aggregated_values_field(&customization_block)
+ customize_grouped_by_field(&customization_block)
+ customize_sub_aggregations_field(&customization_block)
+ customize_sort_order_enum_values(&customization_block)
+ end
+
+ # (see Mixins::HasTypeInfo#json_schema)
+defjson_schema(nullable:nil,**options)
+ ifoptions.key?(:type)
+ raiseErrors::SchemaError,"Cannot override JSON schema type of field `#{name}` with `#{options.fetch(:type)}`"
+ end
+
+ casenullable
+ whentrue
+ raiseErrors::SchemaError,"`nullable: true` is not allowed on a field--just declare the GraphQL field as being nullable (no `!` suffix) instead."
+ whenfalse
+ self.non_nullable_in_json_schema=true
+ end
+
+ super(**options)
+ end
+
+ # Configures ElasticGraph to source a field’s value from a related object. This can be used to denormalize data at ingestion time to
+# support filtering, grouping, sorting, or aggregating data on a field from a related object.
+#
+# @param relationship [String] name of a relationship defined with {TypeWithSubfields#relates_to_one} using an inbound foreign key
+# which contains the the field you wish to source values from
+# @param field_path [String] dot-separated path to the field on the related type containing values that should be copied to this
+# field
+# @return [void]
+#
+# @example Source `City.currency` from `Country.currency`
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Country" do |t|
+# t.field "id", "ID"
+# t.field "name", "String"
+# t.field "currency", "String"
+# t.relates_to_one "capitalCity", "City", via: "capitalCityId", dir: :out
+# t.index "countries"
+# end
+#
+# schema.object_type "City" do |t|
+# t.field "id", "ID"
+# t.field "name", "String"
+# t.relates_to_one "capitalOf", "Country", via: "capitalCityId", dir: :in
+#
+# t.field "currency", "String" do |f|
+# f.sourced_from "capitalOf", "currency"
+# end
+#
+# t.index "cities"
+# end
+# end
+defsourced_from(relationship,field_path)
+ self.source=schema_def_state.factory.new_field_source(
+ relationship_name:relationship,
+ field_path:field_path
+ )
+ end
+
+ # @private
+defruntime_script(script)
+ self.runtime_field_script=script
+ end
+
+ # Registers an old name that this field used to have in a prior version of the schema.
+#
+# @note In situations where this API applies, ElasticGraph will give you an error message indicating that you need to use this API
+# or {TypeWithSubfields#deleted_field}. Likewise, when ElasticGraph no longer needs to know about this, it'll give you a warning
+# indicating the call to this method can be removed.
+#
+# @param old_name [String] old name this field used to have in a prior version of the schema
+# @return [void]
+#
+# @example Indicate that `Widget.description` used to be called `Widget.notes`.
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Widget" do |t|
+# t.field "description", "String" do |f|
+# f.renamed_from "notes"
+# end
+# end
+# end
+defrenamed_from(old_name)
+ schema_def_state.register_renamed_field(
+ parent_type.name,
+ from:old_name,
+ to:name,
+ defined_at:caller_locations(1,1).first,# : ::Thread::Backtrace::Location
+defined_via:%(field.renamed_from "#{old_name}")
+ )
+ end
+
+ # @private
+defto_sdl(type_structure_only:false,default_value_sdl:nil,&arg_selector)
+ iftype_structure_only
+ "#{name}#{args_sdl(joiner:", ",&arg_selector)}: #{type.name}"
+ else
+ args_sdl=args_sdl(joiner:"\n ",after_opening_paren:"\n ",&arg_selector)
+ "#{formatted_documentation}#{name}#{args_sdl}: #{type.name}#{default_value_sdl}#{directives_sdl}".strip
+ end
+ end
+
+ # Indicates if this field is sortable. Sortable fields will have corresponding `_ASC` and `_DESC` values generated in the
+# sort order {EnumType} of the parent indexed type.
+#
+# By default, the sortability is inferred by the field type and mapping. For example, list fields are not sortable,
+# and fields mapped as `text` are not sortable either. Fields are sortable in most other cases.
+#
+# The `sortable: true` option can be used to force a field to be sortable.
+#
+# @return [Boolean] true if this field is sortable
+defsortable?
+ returnsortableunlesssortable.nil?
+
+ # List fields are not sortable by default. We'd need to provide the datastore a sort mode option:
+# https://www.elastic.co/guide/en/elasticsearch/reference/current/sort-search-results.html#_sort_mode_option
+returnfalseiftype.list?
+
+ # Boolean fields are not sortable by default.
+# - Boolean: sorting all falses before all trues (or whatever) is not generally interesting.
+returnfalseiftype.unwrap_non_null.boolean?
+
+ # Elasticsearch/OpenSearch do not support sorting text fields:
+# > Text fields are not used for sorting...
+# (from https://www.elastic.co/guide/en/elasticsearch/reference/current/the datastore.html#text)
+returnfalseiftext?
+
+ # If the type uses custom mapping type we don't know how if the datastore can sort by it, so we assume it's not sortable.
+returnfalseiftype.as_object_type&.has_custom_mapping_type?
+
+ # Default every other field to being sortable.
+true
+ end
+
+ # Indicates if this field is filterable. Filterable fields will be available in the GraphQL schema under the `filter` argument.
+#
+# Most fields are filterable, except when:
+#
+# - It's a relation. Relation fields require us to load the related data from another index and can't be filtered on.
+# - The field is an object type that isn't itself filterable (e.g. due to having no filterable fields or whatever).
+# - Explicitly disabled with `filterable: false`.
+#
+# @return [Boolean]
+deffilterable?
+ # Object types that use custom index mappings (as `GeoLocation` does) aren't filterable
+# by default since we can't guess what datastore filtering capabilities they have. We've implemented
+# filtering support for `GeoLocation` fields, though, so we need to explicitly make it fliterable here.
+# TODO: clean this up using an interface instead of checking for `GeoLocation`.
+returntrueiftype.fully_unwrapped.name=="GeoLocation"
+
+ returnfalseifrelationship||type.fully_unwrapped.as_object_type&.does_not_support?(&:filterable?)
+ returntrueiffilterable.nil?
+ filterable
+ end
+
+ # Indicates if this field is groupable. Groupable fields will be available under `groupedBy` for an aggregations query.
+#
+# Groupability is inferred based on the field type and mapping type, or you can use the `groupable: true` option to force it.
+#
+# @return [Boolean]
+defgroupable?
+ # If the groupability of the field was specified explicitly when the field was defined, use the specified value.
+returngroupableunlessgroupable.nil?
+
+ # We don't want the `id` field of an indexed type to be available to group by, because it's the unique primary key
+# and the groupings would each contain one document. It's simpler and more efficient to just query the raw documents
+# instead.
+returnfalseifparent_type.indexed?&&name=="id"
+
+ returnfalseifrelationship||type.fully_unwrapped.as_object_type&.does_not_support?(&:groupable?)
+
+ # We don't support grouping an entire list of values, but we do support grouping on individual values in a list.
+# However, we only do so when a `singular_name` has been provided (so that we know what to call the grouped_by field).
+# The semantics are a little odd (since one document can be duplicated in multiple grouping buckets) so we're ok
+# with not offering it by default--the user has to opt-in by telling us what to call the field in its singular form.
+returnlist_field_groupable_by_single_values?iftype.list?&&type.fully_unwrapped.leaf?
+
+ # Nested fields will be supported through specific nested aggregation support, and do not
+# work as expected when grouping on the root document type.
+returnfalseifnested?
+
+ # Text fields cannot be efficiently grouped on, so make them non-groupable by default.
+returnfalseiftext?
+
+ # In all other cases, default to being groupable.
+true
+ end
+
+ # Indicates if this field is aggregatable. Aggregatable fields will be available under `aggregatedValues` for an aggregations query.
+#
+# Aggregatability is inferred based on the field type and mapping type, or you can use the `aggregatable: true` option to force it.
+#
+# @return [Boolean]
+defaggregatable?
+ returnaggregatableunlessaggregatable.nil?
+ returnfalseifrelationship
+
+ # We don't yet support aggregating over subfields of a `nested` field.
+# TODO: add support for aggregating over subfields of `nested` fields.
+returnfalseifnested?
+
+ # Text fields are not efficiently aggregatable (and you'll often get errors from the datastore if you attempt to aggregate them).
+returnfalseiftext?
+
+ type_for_derived_types.fully_unwrapped.as_object_type&.supports?(&:aggregatable?)||index_leaf?
+ end
+
+ # Indicates if this field can be used as the basis for a sub-aggregation. Sub-aggregatable fields will be available under
+# `subAggregations` for an aggregations query.
+#
+# Only nested fields, and object fields which have nested fields, can be sub-aggregated.
+#
+# @return [Boolean]
+defsub_aggregatable?
+ returnfalseifrelationship
+
+ nested?||type_for_derived_types.fully_unwrapped.as_object_type&.supports?(&:sub_aggregatable?)
+ end
+
+ # Defines an argument on the field.
+#
+# @note ElasticGraph takes care of defining arguments for all the query features it supports, so there is generally no need to use
+# this API, and it has no way to interpret arbitrary arguments defined on a field. However, it can be useful for extensions that
+# extend the {ElasticGraph::GraphQL} query engine. For example, {ElasticGraph::Apollo} uses this API to satisfy the [Apollo
+# federation subgraph spec](https://www.apollographql.com/docs/federation/federation-spec/).
+#
+# @param name [String] name of the argument
+# @param value_type [String] type of the argument in GraphQL SDL syntax
+# @yield [Argument] for further customization
+#
+# @example Define an argument on a field
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Product" do |t|
+# t.field "name", "String" do |f|
+# f.argument "language", "String"
+# end
+# end
+# end
+defargument(name,value_type,&block)
+ args[name]=schema_def_state.factory.new_argument(
+ self,
+ name,
+ schema_def_state.type_ref(value_type),
+ &block
+ )
+ end
+
+ # The index mapping type in effect for this field. This could come from either the field definition or from the type definition.
+#
+# @return [String]
+defmapping_type
+ backing_indexing_field&.mapping_type||(resolve_mapping||{})["type"]
+ end
+
+ # @private
+deflist_field_groupable_by_single_values?
+ (type.list?||backing_indexing_field&.type&.list?)&&!singular_name.nil?
+ end
+
+ # @private
+defdefine_aggregated_values_field(parent_type)
+ returnunlessaggregatable?
+
+ unwrapped_type_for_derived_types=type_for_derived_types.fully_unwrapped
+ aggregated_values_type=
+ ifindex_leaf?
+ unwrapped_type_for_derived_types.resolved.aggregated_values_type
+ else
+ unwrapped_type_for_derived_types.as_aggregated_values
+ end
+
+ parent_type.fieldname,aggregated_values_type.name,name_in_index:name_in_index,graphql_only:truedo|f|
+ f.documentationderived_documentation("Computed aggregate values for the `#{name}` field")
+ aggregated_values_customizations.each{|block|block.call(f)}
+ end
+ end
+
+ # @private
+defdefine_grouped_by_field(parent_type)
+ returnunless(field_name=grouped_by_field_name)
+
+ parent_type.fieldfield_name,grouped_by_field_type_name,name_in_index:name_in_index,graphql_only:truedo|f|
+ add_grouped_by_field_documentation(f)
+
+ define_legacy_timestamp_grouping_arguments_if_needed(f)iflegacy_grouping_schema
+
+ grouped_by_customizations.each{|block|block.call(f)}
+ end
+ end
+
+ # @private
+defgrouped_by_field_type_name
+ unwrapped_type=type_for_derived_types.fully_unwrapped
+ ifunwrapped_type.scalar_type_needing_grouped_by_object?&&!legacy_grouping_schema
+ unwrapped_type.with_reverted_override.as_grouped_by.name
+ elsifunwrapped_type.leaf?
+ unwrapped_type.name
+ else
+ unwrapped_type.as_grouped_by.name
+ end
+ end
+
+ # @private
+defadd_grouped_by_field_documentation(field)
+ text=iflist_field_groupable_by_single_values?
+ derived_documentation(
+ "The individual value from `#{name}` for this group",
+ list_field_grouped_by_doc_note("`#{name}`")
+ )
+ elsiftype.list?&&type.fully_unwrapped.object?
+ derived_documentation(
+ "The `#{name}` field value for this group",
+ list_field_grouped_by_doc_note("the selected subfields of `#{name}`")
+ )
+ elsiftype_for_derived_types.fully_unwrapped.scalar_type_needing_grouped_by_object?&&!legacy_grouping_schema
+ derived_documentation("Offers the different grouping options for the `#{name}` value within this group")
+ else
+ derived_documentation("The `#{name}` field value for this group")
+ end
+
+ field.documentationtext
+ end
+
+ # @private
+defgrouped_by_field_name
+ returnnilunlessgroupable?
+ list_field_groupable_by_single_values??singular_name:name
+ end
+
+ # @private
+defdefine_sub_aggregations_field(parent_type:,type:)
+ parent_type.fieldname,type,name_in_index:name_in_index,graphql_only:truedo|f|
+ f.documentationderived_documentation("Used to perform a sub-aggregation of `#{name}`")
+ sub_aggregations_customizations.each{|c|c.call(f)}
+
+ yieldfifblock_given?
+ end
+ end
+
+ # @private
+defto_filter_field(parent_type:,for_single_value:!type_for_derived_types.list?)
+ type_prefix=text??"Text":type_for_derived_types.fully_unwrapped.name
+ filter_type=schema_def_state
+ .type_ref(type_prefix)
+ .as_static_derived_type(filter_field_category(for_single_value))
+ .name
+
+ params=to_h
+ .slice(*@@initialize_param_names)
+ .merge(type:filter_type,parent_type:parent_type,name_in_index:name_in_index,type_for_derived_types:nil)
+
+ schema_def_state.factory.new_field(**params).tapdo|f|
+ f.documentationderived_documentation(
+ "Used to filter on the `#{name}` field",
+ "Will be ignored if `null` or an empty object is passed"
+ )
+
+ filter_customizations.each{|c|c.call(f)}
+ end
+ end
+
+ # @private
+defdefine_relay_pagination_arguments!
+ argumentschema_def_state.schema_elements.first.to_sym,"Int"do|a|
+ a.documentation<<~EOS
+ Used in conjunction with the `after` argument to forward-paginate through the `#{name}`.
+ When provided, limits the number of returned results to the first `n` after the provided
+ `after` cursor (or from the start of the `#{name}`, if no `after` cursor is provided).
+
+ See the [Relay GraphQL Cursor Connections
+ Specification](https://relay.dev/graphql/connections.htm#sec-Arguments) for more info.
+ EOS
+end
+
+ argumentschema_def_state.schema_elements.after.to_sym,"Cursor"do|a|
+ a.documentation<<~EOS
+ Used to forward-paginate through the `#{name}`. When provided, the next page after the
+ provided cursor will be returned.
+
+ See the [Relay GraphQL Cursor Connections
+ Specification](https://relay.dev/graphql/connections.htm#sec-Arguments) for more info.
+ EOS
+end
+
+ argumentschema_def_state.schema_elements.last.to_sym,"Int"do|a|
+ a.documentation<<~EOS
+ Used in conjunction with the `before` argument to backward-paginate through the `#{name}`.
+ When provided, limits the number of returned results to the last `n` before the provided
+ `before` cursor (or from the end of the `#{name}`, if no `before` cursor is provided).
+
+ See the [Relay GraphQL Cursor Connections
+ Specification](https://relay.dev/graphql/connections.htm#sec-Arguments) for more info.
+ EOS
+end
+
+ argumentschema_def_state.schema_elements.before.to_sym,"Cursor"do|a|
+ a.documentation<<~EOS
+ Used to backward-paginate through the `#{name}`. When provided, the previous page before the
+ provided cursor will be returned.
+
+ See the [Relay GraphQL Cursor Connections
+ Specification](https://relay.dev/graphql/connections.htm#sec-Arguments) for more info.
+ EOS
+end
+ end
+
+ # Converts this field to an `Indexing::FieldReference`, which contains all the attributes involved
+# in building an `Indexing::Field`. Notably, we cannot actually convert to an `Indexing::Field` at
+# the point this method is called, because the referenced field type may not have been defined
+# yet. We don't need an actual `Indexing::Field` until the very end of the schema definition process,
+# when we are dumping the artifacts. However, we need this at field definition time so that we
+# can correctly detect duplicate indexing field issues when a field is defined. (This is used
+# in `TypeWithSubfields#field`).
+#
+# @private
+defto_indexing_field_reference
+ returnnilifgraphql_only
+
+ Indexing::FieldReference.new(
+ name:name,
+ name_in_index:name_in_index,
+ type:non_nullable_in_json_schema?type.wrap_non_null:type,
+ mapping_options:mapping_options,
+ json_schema_options:json_schema_options,
+ accuracy_confidence:accuracy_confidence,
+ source:source,
+ runtime_field_script:runtime_field_script
+ )
+ end
+
+ # Converts this field to its `IndexingField` form.
+#
+# @private
+defto_indexing_field
+ to_indexing_field_reference&.resolve
+ end
+
+ # @private
+defresolve_mapping
+ to_indexing_field&.mapping
+ end
+
+ # Returns the string paths to the list fields that we need to index counts for.
+# We do this to support the ability to filter on the size of a list.
+#
+# @private
+defpaths_to_lists_for_count_indexing(has_list_ancestor:false)
+ self_path=(has_list_ancestor||type.list?)?[name_in_index]:[]
+
+ nested_paths=
+ # Nested fields get indexed as separate hidden documents:
+# https://www.elastic.co/guide/en/elasticsearch/reference/8.8/nested.html
+#
+# Given that, the counts of any `nested` list subfields will go in a `__counts` field on the
+# separate hidden document.
+if!nested?&&(object_type=type.fully_unwrapped.as_object_type)
+ object_type.indexing_fields_by_name_in_index.values.flat_mapdo|sub_field|
+ sub_field.paths_to_lists_for_count_indexing(has_list_ancestor:has_list_ancestor||type.list?).mapdo|sub_path|
+ "#{name_in_index}#{LIST_COUNTS_FIELD_PATH_KEY_SEPARATOR}#{sub_path}"
+ end
+ end
+ else
+ []
+ end
+
+ self_path+nested_paths
+ end
+
+ # Indicates if this field is a leaf value in the index. Note that GraphQL leaf values
+# are always leaf values in the index but the inverse is not always true. For example,
+# a `GeoLocation` field is not a leaf in GraphQL (because `GeoLocation` is an object
+# type with subfields) but in the index we use a single `geo_point` mapping type, which
+# is a single unit, so we consider it an index leaf.
+#
+# @private
+defindex_leaf?
+ type_for_derived_types.fully_unwrapped.leaf?||DATASTORE_PROPERTYLESS_OBJECT_TYPES.include?(mapping_type)
+ end
+
+ # @private
+ACCURACY_SCORES={
+ # :high is assigned to `Field`s that are generated directly from GraphQL fields or :extra_fields.
+# For these, we know everything available to us in the schema about them.
+high:3,
+
+ # :medium is assigned to `Field`s that are inferred from the id fields required by a relation.
+# We make logical guesses about the `indexing_field_type` but if the field is also manually defined,
+# it could be slightly different (e.g. additional json schema validations), so we have medium
+# confidence of these.
+medium:2,
+
+ # :low is assigned to the ElastcField inferred for the foreign key of an inbound relation. The
+# nullability/cardinality of the foreign key field cannot be known from the relation metadata,
+# so we just guess what seems safest (`[:nullable]`). If the field is defined another way
+# we should prefer it, so we give these fields :low confidence.
+low:1
+ }
+
+ # Given two fields, picks the one that is most accurate. If they have the same accuracy
+# confidence, yields to a block to force it to deal with the discrepancy, unless the fields
+# are exactly equal (in which case we can return either).
+#
+# @private
+defself.pick_most_accurate_from(field1,field2,to_comparable:->(it){it})
+ returnfield1ifto_comparable.call(field1)==to_comparable.call(field2)
+ yieldiffield1.accuracy_confidence==field2.accuracy_confidence
+ # Array#max_by can return nil (when called on an empty array), but our steep type is non-nil.
+# Since it's not smart enough to realize the non-empty-array-usage of `max_by` won't return nil,
+# we have to cast it to untyped here.
+_=[field1,field2].max_by{|f|ACCURACY_SCORES.fetch(f.accuracy_confidence)}
+ end
+
+ # Indicates if the field uses the `nested` mapping type.
+#
+# @private
+defnested?
+ mapping_type=="nested"
+ end
+
+ # Records the `ComputationDetail` that should be on the `runtime_metadata_graphql_field`.
+#
+# @private
+defruntime_metadata_computation_detail(empty_bucket_value:,function:)
+ self.computation_detail=SchemaArtifacts::RuntimeMetadata::ComputationDetail.new(
+ empty_bucket_value:empty_bucket_value,
+ function:function
+ )
+ end
+
+ # Lazily creates and returns a GraphQLField using the field's {#name_in_index}, {#computation_detail},
+# and {#relationship}.
+#
+# @private
+defruntime_metadata_graphql_field
+ SchemaArtifacts::RuntimeMetadata::GraphQLField.new(
+ name_in_index:name_in_index,
+ computation_detail:computation_detail,
+ relation:relationship&.runtime_metadata
+ )
+ end
+
+ private
+
+ defargs_sdl(joiner:,after_opening_paren:"",&arg_selector)
+ selected_args=args.values.select(&arg_selector)
+ args_sdl=selected_args.map(&:to_sdl).flat_map{|s|s.split("\n")}.join(joiner)
+ returnnilifargs_sdl.empty?
+ "(#{after_opening_paren}#{args_sdl})"
+ end
+
+ # Indicates if the field uses the `text` mapping type.
+deftext?
+ mapping_type=="text"
+ end
+
+ defdefine_legacy_timestamp_grouping_arguments_if_needed(grouping_field)
+ casetype.fully_unwrapped.name
+ when"Date"
+ grouping_field.argumentschema_def_state.schema_elements.granularity,"DateGroupingGranularity!"do|a|
+ a.documentation"Determines the grouping granularity for this field."
+ end
+
+ grouping_field.argumentschema_def_state.schema_elements.offset_days,"Int"do|a|
+ a.documentation<<~EOS
+ Number of days (positive or negative) to shift the `Date` boundaries of each date grouping bucket.
+
+ For example, when grouping by `YEAR`, this can be used to align the buckets with fiscal or school years instead of calendar years.
+ EOS
+end
+ when"DateTime"
+ grouping_field.argumentschema_def_state.schema_elements.granularity,"DateTimeGroupingGranularity!"do|a|
+ a.documentation"Determines the grouping granularity for this field."
+ end
+
+ grouping_field.argumentschema_def_state.schema_elements.time_zone,"TimeZone"do|a|
+ a.documentation"The time zone to use when determining which grouping a `DateTime` value falls in."
+ a.default"UTC"
+ end
+
+ grouping_field.argumentschema_def_state.schema_elements.offset,"DateTimeGroupingOffsetInput"do|a|
+ a.documentation<<~EOS
+ Amount of offset (positive or negative) to shift the `DateTime` boundaries of each grouping bucket.
+
+ For example, when grouping by `WEEK`, you can shift by 24 hours to change what day-of-week weeks are considered to start on.
+ EOS
+end
+ end
+ end
+
+ deflist_field_grouped_by_doc_note(individual_value_selection_description)
+ <<~EOS.strip
+ Note: `#{name}` is a collection field, but selecting this field will group on individual values of #{individual_value_selection_description}.
+ That means that a document may be grouped into multiple aggregation groupings (i.e. when its `#{name}`
+ field has multiple values) leading to some data duplication in the response. However, if a value shows
+ up in `#{name}` multiple times for a single document, that document will only be included in the group
+ once
+ EOS
+end
+
+ # Determines the suffix of the filter field derived for this field. The suffix used determines
+# the filtering capabilities (e.g. filtering on a single value vs a list of values with `any_satisfy`).
+deffilter_field_category(for_single_value)
+ return:filter_inputiffor_single_value
+
+ # For an index leaf field, there are no further nesting paths to traverse. We want to directly
+# use a `ListFilterInput` type (e.g. `IntListFilterInput`) to offer `any_satisfy` filtering at this level.
+return:list_filter_inputifindex_leaf?
+
+ # If it's a list-of-objects field we require the user to tell us what mapping type they want to
+# use, which determines the suffix (and is handled below). Otherwise, we want to use `FieldsListFilterInput`.
+# We are within a list filtering context (as indicated by `for_single_value` being false) without
+# being at an index leaf field, so we must use `FieldsListFilterInput` as there are further nesting paths
+# on the document and we want to provide `any_satisfy` at the leaf fields.
+return:fields_list_filter_inputunlesstype_for_derived_types.list?
+
+ casemapping_type
+ when"nested"then:list_filter_input
+ when"object"then:fields_list_filter_input
+ else
+ raiseErrors::SchemaError,<<~EOS
+ `#{parent_type.name}.#{name}` is a list-of-objects field, but the mapping type has not been explicitly specified. Elasticsearch and OpenSearch
+ offer two ways to index list-of-objects fields. It cannot be changed on an existing field without dropping the index and recreating it (losing
+ any existing indexed data!), and there are nuanced tradeoffs involved here, so ElasticGraph provides no default mapping in this situation.
+
+ If you're currently prototyping and don't want to spend time weighing this tradeoff, we recommend you do this:
+
+ ```
+ t.field "#{name}", "#{type.name}" do |f|
+ # Here we are opting for flexibility (nested) over pure performance (object).
+ # TODO: evaluate if we want to stick with `nested` before going to production.
+ f.mapping type: "nested"
+ end
+ ```
+
+ Read on for details of the tradeoff involved here.
+
+ -----------------------------------------------------------------------------------------------------------------------------
+
+ Here are the options:
+
+ 1) `f.mapping type: "object"` will cause each field path to be indexed as a separate "flattened" list.
+
+ For example, given a `Film` document like this:
+
+ ```
+ {
+ "name": "The Empire Strikes Back",
+ "characters": [
+ {"first": "Luke", "last": "Skywalker"},
+ {"first": "Han", "last": "Solo"}
+ ]
+ }
+ ```
+
+ ...the data will look like this in the inverted Lucene index:
+
+ ```
+ {
+ "name": "The Empire Strikes Back",
+ "characters.first": ["Luke", "Han"],
+ "characters.last": ["Skywalker", "Solo"]
+ }
+ ```
+
+ This is highly efficient, but there is no way to search on multiple fields of a character and be sure that the matching values came from the same character.
+ ElasticGraph models this in the filtering API it offers for this case:
+
+ ```
+ query {
+ films(filter: {
+ characters: {
+ first: {#{schema_def_state.schema_elements.any_satisfy}: {#{schema_def_state.schema_elements.equal_to_any_of}: ["Luke"]}}
+ last: {#{schema_def_state.schema_elements.any_satisfy}: {#{schema_def_state.schema_elements.equal_to_any_of}: ["Skywalker"]}}
+ }
+ }) {
+ # ...
+ }
+ }
+ ```
+
+ As suggested by this filtering API, this will match any film that has a character with a first name of "Luke" and a character
+ with the last name of "Skywalker", but this could be satisfied by two separate characters.
+
+ 2) `f.mapping type: "nested"` will cause each _object_ in the list to be indexed as a separate hidden document, preserving the independence of each.
+
+ Given a `Film` document like "The Empire Strikes Back" from above, the `nested` type will index separate hidden documents for each character. This
+ allows ElasticGraph to offer this filtering API instead:
+
+ ```
+ query {
+ films(filter: {
+ characters: {#{schema_def_state.schema_elements.any_satisfy}: {
+ first: {#{schema_def_state.schema_elements.equal_to_any_of}: ["Luke"]}
+ last: {#{schema_def_state.schema_elements.equal_to_any_of}: ["Skywalker"]}
+ }}
+ }) {
+ # ...
+ }
+ }
+ ```
+
+ As suggested by this filtering API, this will only match films that have a character named "Luke Skywalker". However, the Elasticsearch docs[^1][^2] warn
+ that the `nested` mapping type can lead to performance problems, and index sorting cannot be configured[^3] when the `nested` type is used.
+
+ [^1]: https://www.elastic.co/guide/en/elasticsearch/reference/8.10/nested.html
+ [^2]: https://www.elastic.co/guide/en/elasticsearch/reference/8.10/joining-queries.html
+ [^3]: https://www.elastic.co/guide/en/elasticsearch/reference/8.10/index-modules-index-sorting.html
+ EOS
+end
+ end
+end
+
+
+
+
+
+
+
+
+
+
Instance Method Details
+
+
+
+
+
+ #aggregatable? ⇒ Boolean
+
+
+
+
+
+
+
+
Indicates if this field is aggregatable. Aggregatable fields will be available under aggregatedValues for an aggregations query.
+
+
Aggregatability is inferred based on the field type and mapping type, or you can use the aggregatable: true option to force it.
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/schema_elements/field.rb', line 584
+
+defaggregatable?
+ returnaggregatableunlessaggregatable.nil?
+ returnfalseifrelationship
+
+ # We don't yet support aggregating over subfields of a `nested` field.
+# TODO: add support for aggregating over subfields of `nested` fields.
+returnfalseifnested?
+
+ # Text fields are not efficiently aggregatable (and you'll often get errors from the datastore if you attempt to aggregate them).
+returnfalseiftext?
+
+ type_for_derived_types.fully_unwrapped.as_object_type&.supports?(&:aggregatable?)||index_leaf?
+end
ElasticGraph takes care of defining arguments for all the query features it supports, so there is generally no need to use
+this API, and it has no way to interpret arbitrary arguments defined on a field. However, it can be useful for extensions that
+extend the GraphQL query engine. For example, Apollo uses this API to satisfy the Apollo
+federation subgraph spec.
+
+
+
+
Defines an argument on the field.
+
+
+
+
+
+
+
+
Examples:
+
+
+
Define an argument on a field
+
+
+
ElasticGraph.define_schemado|schema|
+ schema.object_type"Product"do|t|
+ t.field"name","String"do|f|
+ f.argument"language","String"
+ end
+ end
+end
For each field defined in your schema that is aggregatable, a corresponding aggregatedValues field will be created on the
+*AggregatedValues type derived from the parent object type.
+
+
+
+
This method returns an undefined value.
Registers a customization callback that will be applied to the corresponding aggregatedValues field that will be generated for
+this field.
+
+
+
+
+
+
+
+
Examples:
+
+
+
Mark CampaignAggregatedValues.adImpressions with @deprecated
+
+
+
ElasticGraph.define_schemado|schema|
+ schema.object_type"Campaign"do|t|
+ t.field"id","ID"
+
+ t.field"adImpressions","Int"do|f|
+ f.customize_aggregated_values_fielddo|avf|
+ avf.directive"deprecated"
+ end
+ end
+
+ t.index"campaigns"
+ end
+end
For each field defined in your schema that is filterable, a corresponding filtering field will be created on the
+*FilterInput type derived from the parent object type.
+
+
+
+
This method returns an undefined value.
Registers a customization callback that will be applied to the corresponding filtering field that will be generated for this
+field.
+
+
+
+
+
+
+
+
Examples:
+
+
+
Mark CampaignFilterInput.organizationId with @deprecated
+
+
+
ElasticGraph.define_schemado|schema|
+ schema.object_type"Campaign"do|t|
+ t.field"id","ID"
+
+ t.field"organizationId","ID"do|f|
+ f.customize_filter_fielddo|ff|
+ ff.directive"deprecated"
+ end
+ end
+
+ t.index"campaigns"
+ end
+end
For each field defined in your schema that is groupable, a corresponding groupedBy field will be created on the
+*AggregationGroupedBy type derived from the parent object type.
+
+
+
+
This method returns an undefined value.
Registers a customization callback that will be applied to the corresponding groupedBy field that will be generated for this
+field.
+
+
+
+
+
+
+
+
Examples:
+
+
+
Mark CampaignGroupedBy.organizationId with @deprecated
+
+
+
ElasticGraph.define_schemado|schema|
+ schema.object_type"Campaign"do|t|
+ t.field"id","ID"
+
+ t.field"organizationId","ID"do|f|
+ f.customize_grouped_by_fielddo|gbf|
+ gbf.directive"deprecated"
+ end
+ end
+
+ t.index"campaigns"
+ end
+end
for each sortable field, enum values will be generated on the derived sort order enum type allowing you to
+sort by the field ASC or DESC.
+
+
+
+
This method returns an undefined value.
Registers a customization callback that will be applied to the corresponding enum values that will be generated for this field
+on the derived SortOrder enum type.
+
+
+
+
+
+
+
+
Examples:
+
+
+
Mark CampaignSortOrder.organizationId_(ASC|DESC) with @deprecated
+
+
+
ElasticGraph.define_schemado|schema|
+ schema.object_type"Campaign"do|t|
+ t.field"id","ID"
+
+ t.field"organizationId","ID"do|f|
+ f.customize_sort_order_enum_valuesdo|soev|
+ soev.directive"deprecated"
+ end
+ end
+
+ t.index"campaigns"
+ end
+end
For each field defined in your schema that is sub-aggregatable (e.g. list fields indexed using the nested mapping type),
+
+
+
+
This method returns an undefined value.
a corresponding field will be created on the *AggregationSubAggregations type derived from the parent object type.
+
+
Registers a customization callback that will be applied to the corresponding subAggregations field that will be generated for
+this field.
+
+
+
+
+
+
+
+
Examples:
+
+
+
Mark TransactionAggregationSubAggregations.fees with @deprecated
+
+
+
ElasticGraph.define_schemado|schema|
+ schema.object_type"Transaction"do|t|
+ t.field"id","ID"
+
+ t.field"fees","[Money!]!"do|f|
+ f.mappingtype:"nested"
+
+ f.customize_sub_aggregations_fielddo|saf|
+ # Adds a `@deprecated` directive to the `PaymentAggregationSubAggregations.fees`
+# field without also adding it to the `Payment.fees` field.
+saf.directive"deprecated"
+ end
+ end
+
+ t.index"transactions"
+ end
+
+ schema.object_type"Money"do|t|
+ t.field"amount","Int"
+ t.field"currency","String"
+ end
+end
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/schema_elements/field.rb', line 534
+
+deffilterable?
+ # Object types that use custom index mappings (as `GeoLocation` does) aren't filterable
+# by default since we can't guess what datastore filtering capabilities they have. We've implemented
+# filtering support for `GeoLocation` fields, though, so we need to explicitly make it fliterable here.
+# TODO: clean this up using an interface instead of checking for `GeoLocation`.
+returntrueiftype.fully_unwrapped.name=="GeoLocation"
+
+ returnfalseifrelationship||type.fully_unwrapped.as_object_type&.does_not_support?(&:filterable?)
+ returntrueiffilterable.nil?
+ filterable
+end
+
+
+
+
+
+
+
+
+ #groupable? ⇒ Boolean
+
+
+
+
+
+
+
+
Indicates if this field is groupable. Groupable fields will be available under groupedBy for an aggregations query.
+
+
Groupability is inferred based on the field type and mapping type, or you can use the groupable: true option to force it.
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/schema_elements/field.rb', line 551
+
+defgroupable?
+ # If the groupability of the field was specified explicitly when the field was defined, use the specified value.
+returngroupableunlessgroupable.nil?
+
+ # We don't want the `id` field of an indexed type to be available to group by, because it's the unique primary key
+# and the groupings would each contain one document. It's simpler and more efficient to just query the raw documents
+# instead.
+returnfalseifparent_type.indexed?&&name=="id"
+
+ returnfalseifrelationship||type.fully_unwrapped.as_object_type&.does_not_support?(&:groupable?)
+
+ # We don't support grouping an entire list of values, but we do support grouping on individual values in a list.
+# However, we only do so when a `singular_name` has been provided (so that we know what to call the grouped_by field).
+# The semantics are a little odd (since one document can be duplicated in multiple grouping buckets) so we're ok
+# with not offering it by default--the user has to opt-in by telling us what to call the field in its singular form.
+returnlist_field_groupable_by_single_values?iftype.list?&&type.fully_unwrapped.leaf?
+
+ # Nested fields will be supported through specific nested aggregation support, and do not
+# work as expected when grouping on the root document type.
+returnfalseifnested?
+
+ # Text fields cannot be efficiently grouped on, so make them non-groupable by default.
+returnfalseiftext?
+
+ # In all other cases, default to being groupable.
+true
+end
We recommend using JSON schema validations in a limited fashion. Validations that are appropriate to apply when data is
+entering the system-of-record are often not appropriate on a secondary index like ElasticGraph. Events that violate a JSON
+schema validation will fail to index (typically they will be sent to the dead letter queue and page an oncall engineer). If an
+ElasticGraph instance is meant to contain all the data of some source system, you probably don’t want it applying stricter
+validations than the source system itself has. We recommend limiting your JSON schema validations to situations where
+violations would prevent ElasticGraph from operating correctly.
+
+
+
+
This method returns an undefined value.
Defines the JSON schema validations for this field or type. Validations
+defined here will be included in the generated json_schemas.yaml artifact, which is used by the ElasticGraph indexer to
+validate events before indexing their data in the datastore. In addition, the publisher may use json_schemas.yaml for code
+generation and to apply validation before publishing an event to ElasticGraph.
+
+
Can be called multiple times; each time, the options will be merged into the existing options.
+
+
This is required on a ScalarType (since we don’t know how a custom scalar type should be represented in
+JSON!). On a ElasticGraph::SchemaDefinition::SchemaElements::Field, this is optional, but can be used to make the JSON schema validation stricter then it
+would otherwise be. For example, you could use json_schema maxLength: 30 on a String field to limit the length.
+
+
You can use any of the JSON schema validation keywords here. In addition, nullable: false is supported to configure the
+generated JSON schema to disallow null values for the field. Note that if you define a field with a non-nullable GraphQL type
+(e.g. Int!), the JSON schema will automatically disallow nulls. However, as explained in the
+TypeWithSubfields#field documentation, we generally recommend against defining non-nullable GraphQL fields.
+json_schema nullable: false will disallow null values from being indexed, while still keeping the field nullable in the
+GraphQL schema. If you think you might want to make a field non-nullable in the GraphQL schema some day, it’s a good idea to use
+json_schema nullable: false now to ensure every indexed record has a non-null value for the field.
+
+
+
+
+
+
+
+
Examples:
+
+
+
Define the JSON schema validations of a custom scalar type
+
+
+
ElasticGraph.define_schemado|schema|
+ schema.scalar_type"URL"do|t|
+ t.mappingtype:"keyword"
+
+ # JSON schema has a built-in URI format validator:
+# https://json-schema.org/understanding-json-schema/reference/string.html#resource-identifiers
+t.json_schematype:"string",format:"uri"
+ end
+end
+
+
+
Define additional validations on a field
+
+
+
ElasticGraph.define_schemado|schema|
+ schema.object_type"Card"do|t|
+ t.field"id","ID!"
+
+ t.field"expYear","Int"do|f|
+ # Use JSON schema to ensure the publisher is sending us 4 digit years, not 2 digit years.
+f.json_schemaminimum:2000,maximum:2099
+ end
+
+ t.field"expMonth","Int"do|f|
+ f.json_schemaminimum:1,maximum:12
+ end
+
+ t.index"cards"
+ end
+end
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/schema_elements/field.rb', line 398
+
+defjson_schema(nullable:nil,**options)
+ ifoptions.key?(:type)
+ raiseErrors::SchemaError,"Cannot override JSON schema type of field `#{name}` with `#{options.fetch(:type)}`"
+ end
+
+ casenullable
+ whentrue
+ raiseErrors::SchemaError,"`nullable: true` is not allowed on a field--just declare the GraphQL field as being nullable (no `!` suffix) instead."
+ whenfalse
+ self.non_nullable_in_json_schema=true
+ end
+
+ super(**options)
+end
+
+
+
+
+
+
+
+
+ #mapping_type ⇒ String
+
+
+
+
+
+
+
+
The index mapping type in effect for this field. This could come from either the field definition or from the type definition.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String)
+
+
+
+
+
+
+
+
+
+
+
+
+
+641
+642
+643
+
+
+
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/schema_elements/field.rb', line 641
+
+defmapping_type
+ backing_indexing_field&.mapping_type||(resolve_mapping||{})["type"]
+end
Multiple EnumValues (both *_ASC and *_DESC) are generated on the *SortOrderEnumType derived from the parent indexed
+ObjectType. This is used by clients to sort by a field.
+
+
+
This method registers a customization callback which is applied to every element that is generated for this field.
+
+
+
+
+
+
+
+
Examples:
+
+
+
ElasticGraph.define_schemado|schema|
+ schema.object_type"Transaction"do|t|
+ t.field"id","ID"
+
+ t.field"amount","Int"do|f|
+ f.on_each_generated_schema_elementdo|element|
+ # Adds a `@deprecated` directive to every GraphQL schema element generated for `amount`:
+#
+# - The `Transaction.amount` field.
+# - The `TransactionFilterInput.amount` field.
+# - The `TransactionAggregationGroupedBy.amount` field.
+# - The `TransactionAggregatedValues.amount` field.
+# - The `TransactionSortOrder.amount_ASC` and`TransactionSortOrder.amount_DESC` enum values.
+element.directive"deprecated"
+ end
+ end
+
+ t.index"transactions"
+ end
+end
In situations where this API applies, ElasticGraph will give you an error message indicating that you need to use this API
+or TypeWithSubfields#deleted_field. Likewise, when ElasticGraph no longer needs to know about this, it’ll give you a warning
+indicating the call to this method can be removed.
+
+
+
+
This method returns an undefined value.
Registers an old name that this field used to have in a prior version of the schema.
+
+
+
+
+
+
+
+
Examples:
+
+
+
Indicate that Widget.description used to be called Widget.notes.
+
+
+
ElasticGraph.define_schemado|schema|
+ schema.object_type"Widget"do|t|
+ t.field"description","String"do|f|
+ f.renamed_from"notes"
+ end
+ end
+end
+
+
+
Parameters:
+
+
+
+
+ old_name
+
+
+ (String)
+
+
+
+ —
+
old name this field used to have in a prior version of the schema
Indicates if this field is sortable. Sortable fields will have corresponding _ASC and _DESC values generated in the
+sort order EnumType of the parent indexed type.
+
+
By default, the sortability is inferred by the field type and mapping. For example, list fields are not sortable,
+and fields mapped as text are not sortable either. Fields are sortable in most other cases.
+
+
The sortable: true option can be used to force a field to be sortable.
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/schema_elements/field.rb', line 502
+
+defsortable?
+ returnsortableunlesssortable.nil?
+
+ # List fields are not sortable by default. We'd need to provide the datastore a sort mode option:
+# https://www.elastic.co/guide/en/elasticsearch/reference/current/sort-search-results.html#_sort_mode_option
+returnfalseiftype.list?
+
+ # Boolean fields are not sortable by default.
+# - Boolean: sorting all falses before all trues (or whatever) is not generally interesting.
+returnfalseiftype.unwrap_non_null.boolean?
+
+ # Elasticsearch/OpenSearch do not support sorting text fields:
+# > Text fields are not used for sorting...
+# (from https://www.elastic.co/guide/en/elasticsearch/reference/current/the datastore.html#text)
+returnfalseiftext?
+
+ # If the type uses custom mapping type we don't know how if the datastore can sort by it, so we assume it's not sortable.
+returnfalseiftype.as_object_type&.has_custom_mapping_type?
+
+ # Default every other field to being sortable.
+true
+end
Configures ElasticGraph to source a field’s value from a related object. This can be used to denormalize data at ingestion time to
+support filtering, grouping, sorting, or aggregating data on a field from a related object.
name of a relationship defined with TypeWithSubfields#relates_to_one using an inbound foreign key
+which contains the the field you wish to source values from
+
+
+
+
+
+
+ field_path
+
+
+ (String)
+
+
+
+ —
+
dot-separated path to the field on the related type containing values that should be copied to this
+field
Indicates if this field can be used as the basis for a sub-aggregation. Sub-aggregatable fields will be available under
+subAggregations for an aggregations query.
+
+
Only nested fields, and object fields which have nested fields, can be sub-aggregated.
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/schema_elements/field.rb', line 158
+
+deftype
+ # Here we lazily convert the `original_type` to an input type as needed. This must be lazy because
+# the logic of `as_input` depends on detecting whether the type is an enum type, which it may not
+# be able to do right away--we assume not if we can't tell, and retry every time this method is called.
+original_type.to_final_form(as_input:as_input)
+end
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/main/ElasticGraph/SchemaDefinition/SchemaElements/InterfaceType.html b/docs/main/ElasticGraph/SchemaDefinition/SchemaElements/InterfaceType.html
new file mode 100644
index 00000000..deaf0de2
--- /dev/null
+++ b/docs/main/ElasticGraph/SchemaDefinition/SchemaElements/InterfaceType.html
@@ -0,0 +1,280 @@
+
+
+
+
+
+
+ Class: ElasticGraph::SchemaDefinition::SchemaElements::InterfaceType
+
+ — Documentation by YARD 0.9.37
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Defines a GraphQL interface. Use it to define an abstract supertype with
+one or more fields that concrete implementations of the interface must also define. Each implementation can be an
+ObjectType or InterfaceType.
+
+
+
+
+
+
+
+
Examples:
+
+
+
Define an interface
+
+
+
ElasticGraph.define_schemado|schema|
+ schema.interface_type"Athlete"do|t|
+ # in the block, `t` is an InterfaceType
+end
+end
Defines a GraphQL object type Use it to define a concrete type that
+has subfields. Object types can either be indexed (e.g. directly indexed in the datastore, and available to query from the
+root Query object) or embedded in other indexed types.
+
+
+
+
+
+
+
+
Examples:
+
+
+
Define an object type
+
+
+
ElasticGraph.define_schemado|schema|
+ schema.object_type"Money"do|t|
+ # in the block, `t` is an ObjectType
+end
+end
ElasticGraph.define_schemado|schema|
+ schema.object_type"Orchestra"do|t|
+ t.field"id","ID"
+ t.relates_to_many"musicians","Musician",via:"orchestraId",dir::in,singular:"musician"do|r|
+ # In this block, `r` is a `Relationship`.
+end
+ t.index"orchestras"
+ end
+
+ schema.object_type"Musician"do|t|
+ t.field"id","ID"
+ t.field"instrument","String"
+ t.relates_to_one"orchestra","Orchestra",via:"orchestraId",dir::outdo|r|
+ # In this block, `r` is a `Relationship`.
+end
+ t.index"musicians"
+ end
+end
Indicates that path (a field on the related type) is the equivalent of locally_named on this type.
+
+
Use this API to specify a local field’s equivalent path on the related type. This must be used on relationships used by
+Field#sourced_from when the local type uses Indexing::Index#route_with or Indexing::Index#rollover so that
+ElasticGraph can determine what field from the related type to use to route the update requests to the correct index and shard.
+
+
+
+
+
+
+
+
Examples:
+
+
+
ElasticGraph.define_schemado|schema|
+ schema.object_type"Campaign"do|t|
+ t.field"id","ID!"
+ t.field"name","String"
+ t.field"createdAt","DateTime"
+
+ t.relates_to_one"launchPlan","CampaignLaunchPlan",via:"campaignId",dir::indo|r|
+ r.equivalent_field"campaignCreatedAt",locally_named:"createdAt"
+ end
+
+ t.field"launchDate","Date"do|f|
+ f.sourced_from"launchPlan","launchDate"
+ end
+
+ t.index"campaigns"do|i|
+ i.rollover:yearly,"createdAt"
+ end
+ end
+
+ schema.object_type"CampaignLaunchPlan"do|t|
+ t.field"id","ID"
+ t.field"campaignId","ID"
+ t.field"campaignCreatedAt","DateTime"
+ t.field"launchDate","Date"
+
+ t.index"campaign_launch_plans"
+ end
+end
+
+
+
Parameters:
+
+
+
+
+ path
+
+
+ (String)
+
+
+
+ —
+
path to a routing or rollover field on the related type
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/schema_elements/relationship.rb', line 125
+
+defequivalent_field(path,locally_named:path)
+ if@equivalent_field_paths_by_local_path.key?(locally_named)
+ raiseErrors::SchemaError,"`equivalent_field` has been called multiple times on `#{parent_type.name}.#{name}` with the same " \
+ "`locally_named` value (#{locally_named.inspect}), but each local field can have only one `equivalent_field`."
+ else
+ @equivalent_field_paths_by_local_path[locally_named]=path
+ end
+end
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/main/ElasticGraph/SchemaDefinition/SchemaElements/ScalarType.html b/docs/main/ElasticGraph/SchemaDefinition/SchemaElements/ScalarType.html
new file mode 100644
index 00000000..517d9857
--- /dev/null
+++ b/docs/main/ElasticGraph/SchemaDefinition/SchemaElements/ScalarType.html
@@ -0,0 +1,1456 @@
+
+
+
+
+
+
+ Class: ElasticGraph::SchemaDefinition::SchemaElements::ScalarType
+
+ — Documentation by YARD 0.9.37
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Defines a GraphQL scalar type. ElasticGraph itself uses this to define a few
+common scalar types (e.g. Date and DateTime), but it is also available to you to use to define your own custom scalar types.
+
+
+
+
+
+
+
+
Examples:
+
+
+
Define a scalar type
+
+
+
ElasticGraph.define_schemado|schema|
+ schema.scalar_type"URL"do|t|
+ t.mappingtype:"keyword"
+ t.json_schematype:"string",format:"uri"
+ end
+end
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/schema_elements/scalar_type.rb', line 42
+
+classScalarType<Struct.new(:schema_def_state,:type_ref,:mapping_type,:runtime_metadata,:aggregated_values_customizations)
+ # `Struct.new` provides the following methods:
+# @dynamic type_ref, runtime_metadata
+prependMixins::VerifiesGraphQLName
+ includeMixins::CanBeGraphQLOnly
+ includeMixins::HasDocumentation
+ includeMixins::HasDirectives
+ includeMixins::HasDerivedGraphQLTypeCustomizations
+ includeMixins::HasReadableToSAndInspect.new{|t|t.name}
+
+ # `HasTypeInfo` provides the following methods:
+# @dynamic mapping_options, json_schema_options
+includeMixins::HasTypeInfo
+
+ # @dynamic graphql_only?
+
+ # @private
+definitialize(schema_def_state,name)
+ super(schema_def_state,schema_def_state.type_ref(name).to_final_form)
+
+ # Default the runtime metadata before yielding, so it can be overridden as needed.
+self.runtime_metadata=SchemaArtifacts::RuntimeMetadata::ScalarType.new(
+ coercion_adapter_ref:SchemaArtifacts::RuntimeMetadata::ScalarType::DEFAULT_COERCION_ADAPTER_REF,
+ indexing_preparer_ref:SchemaArtifacts::RuntimeMetadata::ScalarType::DEFAULT_INDEXING_PREPARER_REF
+ )
+
+ yieldself
+
+ missing=[
+ ("`mapping`"ifmapping_options.empty?),
+ ("`json_schema`"ifjson_schema_options.empty?)
+ ].compact
+
+ ifmissing.any?
+ raiseErrors::SchemaError,"Scalar types require `mapping` and `json_schema` to be configured, but `#{name}` lacks #{missing.join(" and ")}."
+ end
+ end
+
+ # @return [String] name of the scalar type
+defname
+ type_ref.name
+ end
+
+ # (see Mixins::HasTypeInfo#mapping)
+defmapping(**options)
+ self.mapping_type=options.fetch(:type)do
+ raiseErrors::SchemaError,"Must specify a mapping `type:` on custom scalars but was missing on the `#{name}` type."
+ end
+
+ super
+ end
+
+ # Specifies the scalar coercion adapter that should be used for this scalar type. The scalar coercion adapter is responsible
+# for validating and coercing scalar input values, and converting scalar return values to a form suitable for JSON serialization.
+#
+# @note For examples of scalar coercion adapters, see `ElasticGraph::GraphQL::ScalarCoercionAdapters`.
+# @note If the `defined_at` require path requires any directories be put on the Ruby `$LOAD_PATH`, you are responsible for doing
+# that before booting {ElasticGraph::GraphQL}.
+#
+# @param adapter_name [String] fully qualified Ruby class name of the adapter
+# @param defined_at [String] the `require` path of the adapter
+# @return [void]
+#
+# @example Register a coercion adapter
+# ElasticGraph.define_schema do |schema|
+# schema.scalar_type "PhoneNumber" do |t|
+# t.mapping type: "keyword"
+# t.json_schema type: "string", pattern: "^\\+[1-9][0-9]{1,14}$"
+# t.coerce_with "CoercionAdapters::PhoneNumber", defined_at: "./coercion_adapters/phone_number"
+# end
+# end
+defcoerce_with(adapter_name,defined_at:)
+ self.runtime_metadata=runtime_metadata.with(coercion_adapter_ref:{
+ "extension_name"=>adapter_name,
+ "require_path"=>defined_at
+ }).tap(&:load_coercion_adapter)# verify the adapter is valid.
+end
+
+ # Specifies an indexing preparer that should be used for this scalar type. The indexing preparer is responsible for preparing
+# scalar values before indexing them, performing any desired formatting or normalization.
+#
+# @note For examples of scalar coercion adapters, see `ElasticGraph::Indexer::IndexingPreparers`.
+# @note If the `defined_at` require path requires any directories be put on the Ruby `$LOAD_PATH`, you are responsible for doing
+# that before booting {ElasticGraph::GraphQL}.
+#
+# @param preparer_name [String] fully qualified Ruby class name of the indexing preparer
+# @param defined_at [String] the `require` path of the preparer
+# @return [void]
+#
+# @example Register an indexing preparer
+# ElasticGraph.define_schema do |schema|
+# schema.scalar_type "PhoneNumber" do |t|
+# t.mapping type: "keyword"
+# t.json_schema type: "string", pattern: "^\\+[1-9][0-9]{1,14}$"
+#
+# t.prepare_for_indexing_with "IndexingPreparers::PhoneNumber",
+# defined_at: "./indexing_preparers/phone_number"
+# end
+# end
+defprepare_for_indexing_with(preparer_name,defined_at:)
+ self.runtime_metadata=runtime_metadata.with(indexing_preparer_ref:{
+ "extension_name"=>preparer_name,
+ "require_path"=>defined_at
+ }).tap(&:load_indexing_preparer)# verify the preparer is valid.
+end
+
+ # @return [String] the GraphQL SDL form of this scalar
+defto_sdl
+ "#{formatted_documentation}scalar #{name}#{directives_sdl}"
+ end
+
+ # Registers a block which will be used to customize the derived `*AggregatedValues` object type.
+#
+# @private
+defcustomize_aggregated_values_type(&block)
+ self.aggregated_values_customizations=block
+ end
+
+ # @private
+defaggregated_values_type
+ ifaggregated_values_customizations
+ type_ref.as_aggregated_values
+ else
+ schema_def_state.type_ref("NonNumeric").as_aggregated_values
+ end
+ end
+
+ # @private
+defto_indexing_field_type
+ Indexing::FieldType::Scalar.new(scalar_type:self)
+ end
+
+ # @private
+defderived_graphql_types
+ return[]ifgraphql_only?
+
+ pagination_types=
+ ifschema_def_state.paginated_collection_element_types.include?(name)
+ schema_def_state.factory.build_relay_pagination_types(name,include_total_edge_count:true)
+ else
+ []# : ::Array[ObjectType]
+end
+
+ (to_input_filters+pagination_types).tapdo|derived_types|
+ if(aggregated_values_type=to_aggregated_values_type)
+ derived_types<<aggregated_values_type
+ end
+ end
+ end
+
+ # @private
+defindexed?
+ false
+ end
+
+ private
+
+ EQUAL_TO_ANY_OF_DOC=<<~EOS
+ Matches records where the field value is equal to any of the provided values.
+ This works just like an IN operator in SQL.
+
+ Will be ignored when `null` is passed. When an empty list is passed, will cause this
+ part of the filter to match no documents. When `null` is passed in the list, will
+ match records where the field value is `null`.
+ EOS
+
+ GT_DOC=<<~EOS
+ Matches records where the field value is greater than (>) the provided value.
+
+ Will be ignored when `null` is passed.
+ EOS
+
+ GTE_DOC=<<~EOS
+ Matches records where the field value is greater than or equal to (>=) the provided value.
+
+ Will be ignored when `null` is passed.
+ EOS
+
+ LT_DOC=<<~EOS
+ Matches records where the field value is less than (<) the provided value.
+
+ Will be ignored when `null` is passed.
+ EOS
+
+ LTE_DOC=<<~EOS
+ Matches records where the field value is less than or equal to (<=) the provided value.
+
+ Will be ignored when `null` is passed.
+ EOS
+
+ defto_input_filters
+ # Note: all fields on inputs should be nullable, to support parameterized queries where
+# the parameters are allowed to be set to `null`. We also now support nulls within lists.
+
+ # For floats, we may want to remove the `equal_to_any_of` operator at some point.
+# In many languages. checking exact equality with floats is problematic.
+# For example, in IRB:
+#
+# 2.7.1 :003 > 0.3 == (0.1 + 0.2)
+# => false
+#
+# However, it's not yet clear if that issue will come up with GraphQL, because
+# float values are serialized on the wire as JSON, using an exact decimal
+# string representation. So for now we are keeping `equal_to_any_of`.
+schema_def_state.factory.build_standard_filter_input_types_for_index_leaf_type(name)do|t|
+ # Normally, we use a nullable type for `equal_to_any_of`, to allow a filter expression like this:
+#
+# filter: {optional_field: {equal_to_any_of: [null]}}
+#
+# That filter expression matches documents where `optional_field == null`. However,
+# we cannot support this:
+#
+# filter: {tags: {any_satisfy: {equal_to_any_of: [null]}}}
+#
+# We can't support that because we implement filtering on `null` using an `exists` query:
+# https://www.elastic.co/guide/en/elasticsearch/reference/8.10/query-dsl-exists-query.html
+#
+# ...but that works based on the field existing (or not), and does not let us filter on the
+# presence or absence of `null` within a list.
+#
+# So, here we make the field non-null if we're in an `any_satisfy` context (as indicated by
+# the type ending with `ListElementFilterInput`).
+equal_to_any_of_type=t.type_ref.list_element_filter_input??"[#{name}!]":"[#{name}]"
+
+ t.fieldschema_def_state.schema_elements.equal_to_any_of,equal_to_any_of_typedo|f|
+ f.documentationEQUAL_TO_ANY_OF_DOC
+ end
+
+ ifmapping_type_efficiently_comparable?
+ t.fieldschema_def_state.schema_elements.gt,namedo|f|
+ f.documentationGT_DOC
+ end
+
+ t.fieldschema_def_state.schema_elements.gte,namedo|f|
+ f.documentationGTE_DOC
+ end
+
+ t.fieldschema_def_state.schema_elements.lt,namedo|f|
+ f.documentationLT_DOC
+ end
+
+ t.fieldschema_def_state.schema_elements.lte,namedo|f|
+ f.documentationLTE_DOC
+ end
+ end
+ end
+ end
+
+ defto_aggregated_values_type
+ returnnilunless(customization_block=aggregated_values_customizations)
+ schema_def_state.factory.new_aggregated_values_type_for_index_leaf_type(name,&customization_block)
+ end
+
+ # https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-types.html
+# https://www.elastic.co/guide/en/elasticsearch/reference/7.13/number.html#number
+NUMERIC_TYPES=%w[longintegershortbytedoublefloathalf_floatscaled_floatunsigned_long].to_set
+ DATE_TYPES=%w[datedate_nanos].to_set
+ # The Elasticsearch/OpenSearch docs do not exhaustively give a list of types on which range queries are efficient,
+# but the docs are clear that it is efficient on numeric and date types, and is inefficient on string
+# types: https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-range-query.html
+COMPARABLE_TYPES=NUMERIC_TYPES|DATE_TYPES
+
+ defmapping_type_efficiently_comparable?
+ COMPARABLE_TYPES.include?(mapping_type)
+ end
+end
For examples of scalar coercion adapters, see ElasticGraph::GraphQL::ScalarCoercionAdapters.
+
+
+
+
+ Note:
+
If the defined_at require path requires any directories be put on the Ruby $LOAD_PATH, you are responsible for doing
+that before booting GraphQL.
+
+
+
+
This method returns an undefined value.
Specifies the scalar coercion adapter that should be used for this scalar type. The scalar coercion adapter is responsible
+for validating and coercing scalar input values, and converting scalar return values to a form suitable for JSON serialization.
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/schema_elements/scalar_type.rb', line 113
+
+defcoerce_with(adapter_name,defined_at:)
+ self.runtime_metadata=runtime_metadata.with(coercion_adapter_ref:{
+ "extension_name"=>adapter_name,
+ "require_path"=>defined_at
+ }).tap(&:load_coercion_adapter)# verify the adapter is valid.
+end
+
+
+
+
+
+
+
+
+ #mapping(**options) ⇒ void
+
+
+
+
+
+
+
+
This method returns an undefined value.
Defines the Elasticsearch/OpenSearch field mapping type
+and mapping parameters for a field or type.
+The options passed here will be included in the generated datastore_config.yaml artifact that ElasticGraph uses to configure
+Elasticsearch/OpenSearch.
+
+
Can be called multiple times; each time, the options will be merged into the existing options.
On a Field, this can be used to customize how a field is indexed. For example, String fields are normally
+indexed as keywords; to instead index a String
+field for full text search, you’d need to configure mapping type: "text".
+
+
On a ObjectType, this can be used to use a specific Elasticsearch/OpenSearch data type for something that is
+modeled as an object in GraphQL. For example, we use it for the GeoLocation type so they get indexed in Elasticsearch using the
+geo_point type.
+
+
+
+
+
+
+
+
Examples:
+
+
+
Define the mapping of a custom scalar type
+
+
+
ElasticGraph.define_schemado|schema|
+ schema.scalar_type"URL"do|t|
+ t.mappingtype:"keyword"
+ t.json_schematype:"string",format:"uri"
+ end
+end
+
+
+
Customize the mapping of a field
+
+
+
ElasticGraph.define_schemado|schema|
+ schema.object_type"Card"do|t|
+ t.field"id","ID!"
+
+ t.field"cardholderName","String"do|f|
+ # index this field for full text search
+f.mappingtype:"text"
+ end
+
+ t.field"expYear","Int"do|f|
+ # Use a smaller numeric type to save space in the datastore
+f.mappingtype:"short"
+ f.json_schemaminimum:2000,maximum:2099
+ end
+
+ t.field"expMonth","Int"do|f|
+ # Use a smaller numeric type to save space in the datastore
+f.mappingtype:"byte"
+ f.json_schemaminimum:1,maximum:12
+ end
+
+ t.index"cards"
+ end
+end
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/schema_elements/scalar_type.rb', line 86
+
+defmapping(**options)
+ self.mapping_type=options.fetch(:type)do
+ raiseErrors::SchemaError,"Must specify a mapping `type:` on custom scalars but was missing on the `#{name}` type."
+ end
+
+ super
+end
+
+
+
+
+
+
+
+
+ #name ⇒ String
+
+
+
+
+
+
+
+
Returns name of the scalar type.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String)
+
+
+
+ —
+
name of the scalar type
+
+
+
+
+
+
+
+
+
+
+
+
+81
+82
+83
+
+
+
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/schema_elements/scalar_type.rb', line 81
+
+defname
+ type_ref.name
+end
For examples of scalar coercion adapters, see ElasticGraph::Indexer::IndexingPreparers.
+
+
+
+
+ Note:
+
If the defined_at require path requires any directories be put on the Ruby $LOAD_PATH, you are responsible for doing
+that before booting GraphQL.
+
+
+
+
This method returns an undefined value.
Specifies an indexing preparer that should be used for this scalar type. The indexing preparer is responsible for preparing
+scalar values before indexing them, performing any desired formatting or normalization.
Abstraction for generating derived GraphQL type names based on a collection of formats. A default set of formats is included, and
+overrides can be provided to customize the format we use for naming derived types.
The default formats used for derived GraphQL type names. These formats can be customized by providing derived_type_name_formats
+to RakeTasks or Local::RakeTasks.
Defines a “has many” relationship between the current indexed type and another indexed type by defining a pair of fields clients can use to navigate across indexed types in a single GraphQL query.
Defines a “has one” relationship between the current indexed type and another indexed type by defining a field clients can use to navigate across indexed types in a single GraphQL query.
In situations where this API applies, ElasticGraph will give you an error message indicating that you need to use this API
+or Field#renamed_from. Likewise, when ElasticGraph no longer needs to know about this, it’ll give you a warning indicating
+the call to this method can be removed.
+
+
+
+
This method returns an undefined value.
Registers the name of a field that existed in a prior version of the schema but has been deleted.
+
+
+
+
+
+
+
+
Examples:
+
+
+
Indicate that Widget.description has been deleted
+
+
+
ElasticGraph.define_schemado|schema|
+ schema.object_type"Widget"do|t|
+ t.deleted_field"description"
+ end
+end
+
+
+
Parameters:
+
+
+
+
+ field_name
+
+
+ (String)
+
+
+
+ —
+
name of field that used to exist but has been deleted
Be careful about defining non-nullable fields. Changing a field’s type from non-nullable (e.g. Int!) to nullable (e.g.
+Int) is a breaking change for clients. Making a field non-nullable may also prevent you from applying permissioning to a field
+via an AuthZ layer (as such a layer would have no way to force a field value to null when for a client denied field access).
+Therefore, we recommend limiting your use of ! to only a few situations such as defining a type’s primary key (e.g.
+t.field "id", "ID!") or defining a list field (e.g. t.field "authors", "[String!]!") since empty lists already provide a
+“no data” representation. You can still configure the ElasticGraph indexer to require a non-null value for a field using
+f.json_schema nullable: false.
+
+
+
+
+ Note:
+
ElasticGraph’s understanding of datastore capabilities may override your configured
+aggregatable/filterable/groupable/sortable options. For example, a field indexed as text for full text search will
+not be sortable or groupable even if you pass sortable: true, groupable: true when defining the field, because text fields
+cannot be efficiently sorted by or grouped on.
ElasticGraph.define_schemado|schema|
+ schema.object_type"Campaign"do|t|
+ t.field"id","ID"do|f|
+ f.documentation"The Campaign's identifier."
+ end
+ end
+end
+
+
+
Omit a new field from the GraphQL schema until its data has been backfilled
+
+
+
ElasticGraph.define_schemado|schema|
+ schema.object_type"Campaign"do|t|
+ t.field"id","ID"
+
+ # TODO: remove `indexing_only: true` once the data for this field has been fully backfilled
+t.field"endDate","Date",indexing_only:true
+ end
+end
+
+
+
Use graphql_only to introduce a new name for an existing field
+
+
+
ElasticGraph.define_schemado|schema|
+ schema.object_type"Campaign"do|t|
+ t.field"id","ID"
+
+ t.field"endOn","Date"do|f|
+ f.directive"deprecated",reason:"Use `endDate` instead."
+ end
+
+ # We've decided we want to call the field `endDate` instead of `endOn`, but the data
+# for this field is currently indexed in `endOn`, so we can use `graphql_only` and
+# `name_in_index` to expose the existing data under a new field name.
+t.field"endDate","Date",name_in_index:"endOn",graphql_only:true
+ end
+end
if true, ElasticGraph will define the field as a GraphQL field but omit it from the indexing
+artifacts (json_schemas.yaml and datastore_config.yaml). This can be used along with name_in_index to support careful
+schema evolution.
if true, ElasticGraph will define the field for indexing (in the json_schemas.yaml and
+datastore_config.yaml schema artifact) but will omit it from the GraphQL schema. This can be useful to begin indexing a field
+before you expose it in GraphQL so that you can fully backfill it first.
+
+
+
+
+
+
+ options
+
+
+ (Hash)
+
+
+
+ —
+
a customizable set of options
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Options Hash (**options):
+
+
+
+ name_in_index
+ (String)
+
+
+
+
+ —
the name of the field in the datastore index. Can be used to back a GraphQL field with a
+differently named field in the index.
+
+
+
+
+
+ singular
+ (String)
+
+
+
+
+ —
can be used on a list field (e.g. t.field "tags", "[String!]!", singular: "tag") to tell
+ElasticGraph what the singular form of a field’s name is. When provided, ElasticGraph will define a groupedBy field (using the
+singular form) allowing clients to group by individual values from the field.
+
+
+
+
+
+ aggregatable
+ (Boolean)
+
+
+
+
+ —
force-enables or disables the ability for aggregation queries to aggregate over this field.
+When not provided, ElasticGraph will infer field aggregatability based on the field’s GraphQL type and mapping type.
+
+
+
+
+
+ filterable
+ (Boolean)
+
+
+
+
+ —
force-enables or disables the ability for queries to filter by this field. When not provided,
+ElasticGraph will infer field filterability based on the field’s GraphQL type and mapping type.
+
+
+
+
+
+ groupable
+ (Boolean)
+
+
+
+
+ —
force-enables or disables the ability for aggregation queries to group by this field. When
+not provided, ElasticGraph will infer field groupability based on the field’s GraphQL type and mapping type.
+
+
+
+
+
+ sortable
+ (Boolean)
+
+
+
+
+ —
force-enables or disables the ability for queries to sort by this field. When not provided,
+ElasticGraph will infer field sortability based on the field’s GraphQL type and mapping type.
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/schema_elements/type_with_subfields.rb', line 192
+
+deffield(name,type,graphql_only:false,indexing_only:false,**options)
+ ifreserved_field_names.include?(name)
+ raiseErrors::SchemaError,"Invalid field name: `#{self.name}.#{name}`. `#{name}` is reserved for use by " \
+ "ElasticGraph as a filtering operator. To use it for a field name, add " \
+ "the `schema_element_name_overrides` option (on `ElasticGraph::SchemaDefinition::RakeTasks.new`) to " \
+ "configure an alternate name for the `#{name}` operator."
+ end
+
+ options={name_in_index:nil}.merge(options)ifgraphql_only
+
+ field_factory.call(
+ name:name,
+ type:type,
+ graphql_only:graphql_only,
+ parent_type:wrapping_type,
+ **options
+ )do|field|
+ yieldfieldifblock_given?
+
+ unlessindexing_only
+ register_field(field.name,field,graphql_fields_by_name,"GraphQL",:indexing_only)
+ end
+
+ unlessgraphql_only
+ register_field(field.name_in_index,field,indexing_fields_by_name_in_index,"indexing",:graphql_only)do|f|
+ f.to_indexing_field_reference
+ end
+ end
+ end
+end
+
+
+
+
+
+
+
+
+ #name ⇒ String
+
+
+
+
+
+
+
+
Returns the name of this GraphQL type.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String)
+
+
+
+ —
+
the name of this GraphQL type
+
+
+
+
+
+
+
+
+
+
+
+
+110
+111
+112
+
+
+
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/schema_elements/type_with_subfields.rb', line 110
+
+defname
+ type_ref.name
+end
Bear in mind that pagination does not have much efficiency benefit in this case: all elements of the collection will be
+retrieved when fetching this field from the datastore. The pagination implementation will just trim down the collection before
+returning it.
+
+
+
+
This method returns an undefined value.
An alternative to #field for when you have a list field that you want exposed as a paginated Relay
+connection rather than as a simple list.
+
+
+
+
+
+
+
+
Examples:
+
+
+
Define Author.books as a paginated collection field
indicates what the singular form of a field’s name is. When provided, ElasticGraph will define a
+groupedBy field (using the singular form) allowing clients to group by individual values from the field.
Defines a “has many” relationship between the current indexed type and another indexed type by defining a pair of fields clients
+can use to navigate across indexed types in a single GraphQL query. The pair of generated fields will be Relay Connection
+types allowing you to filter, sort, paginate, and aggregated the
+related data.
+
+
+
+
+
+
+
+
Examples:
+
+
+
Use relates_to_many to define Team.players and Team.playerAggregations
direction of the foreign key. Use :in for an inbound foreign key that resides on the related type and
+references the id of this type. Use :out for an outbound foreign key that resides on this type and references the id of
+the related type.
+
+
+
+
+
+
+ singular
+
+
+ (String)
+
+
+
+ —
+
singular form of the field_name; will be used (along with an Aggregations suffix) for the name of
+the generated aggregations field
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/schema_elements/type_with_subfields.rb', line 397
+
+defrelates_to_many(field_name,type,via:,dir:,singular:)
+ foreign_key_type=(dir==:out)?"[ID!]!":"ID"
+ type_ref=schema_def_state.type_ref(type).to_final_form
+
+ relates_to(field_name,type_ref.as_connection.name,via:via,dir:dir,foreign_key_type:foreign_key_type,cardinality::many,related_type:type)do|f|
+ f.argumentschema_def_state.schema_elements.filter,type_ref.as_filter_input.namedo|a|
+ a.documentation"Used to filter the returned `#{field_name}` based on the provided criteria."
+ end
+
+ f.argumentschema_def_state.schema_elements.order_by,"[#{type_ref.as_sort_order.name}!]"do|a|
+ a.documentation"Used to specify how the returned `#{field_name}` should be sorted."
+ end
+
+ f.define_relay_pagination_arguments!
+
+ yieldfifblock_given?
+ end
+
+ aggregations_name=schema_def_state.schema_elements.normalize_case("#{singular}_aggregations")
+ relates_to(aggregations_name,type_ref.as_aggregation.as_connection.name,via:via,dir:dir,foreign_key_type:foreign_key_type,cardinality::many,related_type:type)do|f|
+ f.argumentschema_def_state.schema_elements.filter,type_ref.as_filter_input.namedo|a|
+ a.documentation"Used to filter the `#{type}` documents that get aggregated over based on the provided criteria."
+ end
+
+ f.define_relay_pagination_arguments!
+
+ yieldfifblock_given?
+
+ f.documentationf.derived_documentation("Aggregations over the `#{field_name}` data")
+ end
+end
Defines a “has one” relationship between the current indexed type and another indexed type by defining a field clients
+can use to navigate across indexed types in a single GraphQL query.
direction of the foreign key. Use :in for an inbound foreign key that resides on the related type and
+references the id of this type. Use :out for an outbound foreign key that resides on this type and references the id of
+the related type.
In situations where this API applies, ElasticGraph will give you an error message indicating that you need to use this API
+or API#deleted_type. Likewise, when ElasticGraph no longer needs to know about this, it’ll give you a warning indicating
+the call to this method can be removed.
+
+
+
+
This method returns an undefined value.
Registers an old name that this type used to have in a prior version of the schema.
+
+
+
+
+
+
+
+
Examples:
+
+
+
Indicate that Widget used to be called Component.
+
+
+
ElasticGraph.define_schemado|schema|
+ schema.object_type"Widget"do|t|
+ t.renamed_from"Component"
+ end
+end
+
+
+
Parameters:
+
+
+
+
+ old_name
+
+
+ (String)
+
+
+
+ —
+
old name this field used to have in a prior version of the schema
Defines a GraphQL union type. Use it to define an abstract supertype with one or
+more concrete subtypes. Each subtype must be an ObjectType, but they do not have to share any fields in common.
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/schema_elements/union_type.rb', line 51
+
+classUnionType<Struct.new(:schema_def_state,:type_ref,:subtype_refs)
+ prependMixins::VerifiesGraphQLName
+ includeMixins::CanBeGraphQLOnly
+ includeMixins::HasDocumentation
+ includeMixins::HasDirectives
+ includeMixins::SupportsFilteringAndAggregation
+ includeMixins::HasIndices
+ includeMixins::HasSubtypes
+ includeMixins::HasDerivedGraphQLTypeCustomizations
+ includeMixins::HasReadableToSAndInspect.new{|t|t.name}
+
+ # @private
+definitialize(schema_def_state,name)
+ super(schema_def_state,schema_def_state.type_ref(name).to_final_form,Set.new)do
+ yieldself
+ end
+ end
+
+ # @return [String] the name of the union type
+defname
+ type_ref.name
+ end
+
+ # Defines a subtype of this union type.
+#
+# @param name [String] the name of an object type which is a member of this union type
+# @return [void]
+#
+# @example
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "Card" do |t|
+# # ...
+# end
+#
+# schema.union_type "FundingSource" do |t|
+# t.subtype "Card"
+# end
+# end
+defsubtype(name)
+ type_ref=schema_def_state.type_ref(name.to_s).to_final_form
+
+ ifsubtype_refs.include?(type_ref)
+ raiseErrors::SchemaError,"Duplicate subtype on UnionType #{self.name}: #{name}"
+ end
+
+ subtype_refs<<type_ref
+ end
+
+ # Defines multiple subtypes of this union type.
+#
+# @param names [Array<String>] names of object types which are members of this union type
+# @return [void]
+#
+# @example Define a union type
+# ElasticGraph.define_schema do |schema|
+# schema.object_type "BankAccount" do |t|
+# # ...
+# end
+#
+# schema.object_type "BitcoinWallet" do |t|
+# # ...
+# end
+#
+# schema.union_type "FundingSource" do |t|
+# t.subtypes "BankAccount", "BitcoinWallet"
+# end
+# end
+defsubtypes(*names)
+ names.flatten.each{|n|subtype(n)}
+ end
+
+ # @return [String] the formatted GraphQL SDL of the union type
+defto_sdl
+ ifsubtype_refs.empty?
+ raiseErrors::SchemaError,"UnionType type #{name} has no subtypes, but must have at least one."
+ end
+
+ "#{formatted_documentation}union #{name}#{directives_sdl(suffix_with:"")}= #{subtype_refs.map(&:name).to_a.join(" | ")}"
+ end
+
+ # @private
+defverify_graphql_correctness!
+ # Nothing to verify. `verify_graphql_correctness!` will be called on each subtype automatically.
+end
+
+ # Various things check `mapping_options` on indexed types (usually object types, but can also happen on union types).
+# We need to implement `mapping_options` here to satisfy those method calls, but we will never use custom mapping on
+# a union type so we hardcode it to return nil.
+#
+# @private
+defmapping_options
+ {}
+ end
+
+ private
+
+ defresolve_subtypes
+ subtype_refs.mapdo|ref|
+ ref.as_object_type||raise(
+ Errors::SchemaError,"The subtype `#{ref}` of the UnionType `#{name}` is not a defined object type."
+ )
+ end
+ end
+end
+
+
+
+
+
+
+
+
+
+
Instance Method Details
+
+
+
+
+
+ #name ⇒ String
+
+
+
+
+
+
+
+
Returns the name of the union type.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String)
+
+
+
+ —
+
the name of the union type
+
+
+
+
+
+
+
+
+
+
+
+
+70
+71
+72
+
+
+
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/schema_elements/union_type.rb', line 70
+
+defname
+ type_ref.name
+end
names of object types which are members of this union type
+
+
+
+
+
+
+
+
+
+
+
+
+
+118
+119
+120
+
+
+
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/schema_elements/union_type.rb', line 118
+
+defsubtypes(*names)
+ names.flatten.each{|n|subtype(n)}
+end
+
+
+
+
+
+
+
+
+ #to_sdl ⇒ String
+
+
+
+
+
+
+
+
Returns the formatted GraphQL SDL of the union type.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String)
+
+
+
+ —
+
the formatted GraphQL SDL of the union type
+
+
+
+
+
+
+
+
+
+
+
+
+123
+124
+125
+126
+127
+128
+129
+
+
+
# File 'elasticgraph-schema_definition/lib/elastic_graph/schema_definition/schema_elements/union_type.rb', line 123
+
+defto_sdl
+ ifsubtype_refs.empty?
+ raiseErrors::SchemaError,"UnionType type #{name} has no subtypes, but must have at least one."
+ end
+
+ "#{formatted_documentation}union #{name}#{directives_sdl(suffix_with:"")}= #{subtype_refs.map(&:name).to_a.join(" | ")}"
+end
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/main/ElasticGraph/Support.html b/docs/main/ElasticGraph/Support.html
new file mode 100644
index 00000000..681d3975
--- /dev/null
+++ b/docs/main/ElasticGraph/Support.html
@@ -0,0 +1,118 @@
+
+
+
+
+
+
+ Module: ElasticGraph::Support
+
+ — Documentation by YARD 0.9.37
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Provides support utilities for the rest of the ElasticGraph gems. As such, it is not intended
+to provide public APIs for ElasticGraph users.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/main/README-1.svg b/docs/main/README-1.svg
new file mode 100644
index 00000000..9f8bf431
--- /dev/null
+++ b/docs/main/README-1.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/main/README-2.svg b/docs/main/README-2.svg
new file mode 100644
index 00000000..762a173d
--- /dev/null
+++ b/docs/main/README-2.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/main/README-3.svg b/docs/main/README-3.svg
new file mode 100644
index 00000000..1a8fa167
--- /dev/null
+++ b/docs/main/README-3.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/main/README-4.svg b/docs/main/README-4.svg
new file mode 100644
index 00000000..4ec0e730
--- /dev/null
+++ b/docs/main/README-4.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/main/README-5.svg b/docs/main/README-5.svg
new file mode 100644
index 00000000..ef912ca0
--- /dev/null
+++ b/docs/main/README-5.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/main/class_list.html b/docs/main/class_list.html
new file mode 100644
index 00000000..f48ce3fc
--- /dev/null
+++ b/docs/main/class_list.html
@@ -0,0 +1,54 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Class List
+
+
+
+
ElasticGraph is a general purpose, near real-time data query and search platform that is scalable and performant,
+serves rich interactive queries, and dramatically simplifies the creation of complex reports. The platform combines
+the power of indexing and search of Elasticsearch or OpenSearch with the query flexibility of GraphQL language.
+Optimized for AWS cloud, it also offers scale and reliability.
+
+
ElasticGraph is a naturally flexible framework with many different possible applications. However, the main motivation we have for
+building it is to power various data APIs, UIs and reports. These modern reports require filtering and aggregations across a body of ever
+growing data sets. Modern APIs allow us to:
+
+
+
Minimize network trips to retrieve your data
+
Get exactly what you want in a single query. No over- or under-serving the data.
+
Push filtering complex calculations to the backend.
+
+
+
Libraries
+
+
ElasticGraph is designed to be modular, with a small core, and many built-in extensions that extend that core
+for specific use cases. This minimizes exposure to vulnerabilities, reduces bloat, and makes ongoing upgrades
+easier. The libraries that ship with ElasticGraph can be broken down into several categories.
+
+
Core Libraries (8 gems)
+
+
These libraries form the core backbone of ElasticGraph that is designed to run in a production deployment. Every ElasticGraph deployment will need to use all of these.
+
+
+
elasticgraph: ElasticGraph meta-gem that pulls in all the core ElasticGraph gems.
+
elasticgraph-admin: ElasticGraph gem that provides datastore administrative tasks, to keep a datastore up-to-date with an ElasticGraph schema.
elasticgraph-query_registry: An ElasticGraph extension that supports safer schema evolution by limiting GraphQL queries based on a registry and validating registered queries against the schema.
+
+
+
Dependency Diagram
+
+
+
+
Datastore Adapters (2 gems)
+
+
These libraries adapt ElasticGraph to your choice of datastore (Elasticsearch or OpenSearch).
These libraries are used for local development of ElasticGraph applications, but are not intended to be deployed to production (except for elasticgraph-rack).
+elasticgraph-rack is used to boot ElasticGraph locally but can also be used to run ElasticGraph in any rack-compatible server (including a Rails application).
+
+
+
elasticgraph-local: Provides support for developing and running ElasticGraph applications locally.
+
elasticgraph-rack: ElasticGraph gem for serving an ElasticGraph GraphQL endpoint using rack.
+
elasticgraph-schema_definition: ElasticGraph gem that provides the schema definition API and generates schema artifacts.
+
+
+
Dependency Diagram
+
+
+
+
Versioning Policy
+
+
ElasticGraph does not strictly follow the SemVer spec. We followed that early in the project’s life
+cycle and realized that it obscures some important compatibility information.
+
+
ElasticGraph’s versioning policy is designed to communicate compatibility information related to the following stakeholders:
+
+
+
Application maintainers: engineers that define an ElasticGraph schema, maintain project configuration, and perform upgrades.
+
Data publishers: systems that publish data into an ElasticGraph application for ingestion by an ElasticGraph indexer.
+
GraphQL clients: clients of the GraphQL API of an ElasticGraph application.
+
+
+
We use the following versioning scheme:
+
+
+
Version numbers are in a 0.MAJOR.MINOR.PATCH format. (The 0. prefix is there in order to reserve 1.0.0 and all later versions
+for after ElasticGraph has been open-sourced).
+
Increments to the PATCH version indicate that the new release contains no backwards incompatibilities for any stakeholders.
+It may contain bug fixes, new features, internal refactorings, and dependency upgrades, among other things. You can expect that
+PATCH level upgrades are always safe–just update the version in your bundle, generate new schema artifacts, and you should be done.
+
Increments to the MINOR version indicate that the new release contains some backwards incompatibilities that may impact the
+application maintainers of some ElasticGraph applications. MINOR releases may include renames to configuration settings,
+changes to the schema definition API, and new schema definition requirements, among other things. You can expect that MINOR
+level upgrades can usually be done in 30 minutes or less (usually in a single commit!), with release notes and clear errors
+from ElasticGraph command line tasks providing guidance on how to upgrade.
+
Increments to the MAJOR version indicate that the new release contains some backwards incompatibilities that may impact the
+data publishers or GraphQL clients of some ElasticGraph applications. MAJOR releases may include changes to the GraphQL
+schema that require careful migration of GraphQL clients or changes to how indexing is done that require a dataset to be
+re-indexed from scratch (e.g. by having data publishers republish their data into an ElasticGraph indexer running the new
+version). You can expect that the release notes will include detailed instructions on how to perform a MAJOR version upgrade.
+
+
+
Deprecation warnings may be included at any of these levels–for example, a PATCH release may contain a deprecation warning
+for a breaking change that may impact application maintainers in an upcoming MINOR release, and a MINOR release may
+contain deprecation warnings for breaking changes that may impact data publishers or GraphQL clients in an upcoming
+MAJOR release.
+
+
Each version level is cumulative over the prior levels. That is, a MINOR release may include PATCH-level changes in addition
+to backwards incompatibilities that may impact application maintainers. A MAJOR release may include PATCH-level or
+MINOR-level changes in addition to backwards incompatibilities that may impact data publishers or GraphQL clients.
+
+
Note that this policy was first adopted in the v0.15.1.0 release. All prior releases aimed (with some occasional mistakes!)
+to follow SemVer with a 0.MAJOR.MINOR.PATCH versioning scheme.
+
+
Note that all gems in this repository share the same version number. Every time we cut a release, we increment the version
+for all gems and release all gems, even if a gem has had no changes since the last release. This is simpler to work with
+than the alternatives.
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/main/file_list.html b/docs/main/file_list.html
new file mode 100644
index 00000000..05465dfd
--- /dev/null
+++ b/docs/main/file_list.html
@@ -0,0 +1,59 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ File List
+
+
+
+
ElasticGraph is a general purpose, near real-time data query and search platform that is scalable and performant,
+serves rich interactive queries, and dramatically simplifies the creation of complex reports. The platform combines
+the power of indexing and search of Elasticsearch or OpenSearch with the query flexibility of GraphQL language.
+Optimized for AWS cloud, it also offers scale and reliability.
+
+
ElasticGraph is a naturally flexible framework with many different possible applications. However, the main motivation we have for
+building it is to power various data APIs, UIs and reports. These modern reports require filtering and aggregations across a body of ever
+growing data sets. Modern APIs allow us to:
+
+
+
Minimize network trips to retrieve your data
+
Get exactly what you want in a single query. No over- or under-serving the data.
+
Push filtering complex calculations to the backend.
+
+
+
Libraries
+
+
ElasticGraph is designed to be modular, with a small core, and many built-in extensions that extend that core
+for specific use cases. This minimizes exposure to vulnerabilities, reduces bloat, and makes ongoing upgrades
+easier. The libraries that ship with ElasticGraph can be broken down into several categories.
+
+
Core Libraries (8 gems)
+
+
These libraries form the core backbone of ElasticGraph that is designed to run in a production deployment. Every ElasticGraph deployment will need to use all of these.
+
+
+
elasticgraph: ElasticGraph meta-gem that pulls in all the core ElasticGraph gems.
+
elasticgraph-admin: ElasticGraph gem that provides datastore administrative tasks, to keep a datastore up-to-date with an ElasticGraph schema.
elasticgraph-query_registry: An ElasticGraph extension that supports safer schema evolution by limiting GraphQL queries based on a registry and validating registered queries against the schema.
+
+
+
Dependency Diagram
+
+
+
+
Datastore Adapters (2 gems)
+
+
These libraries adapt ElasticGraph to your choice of datastore (Elasticsearch or OpenSearch).
These libraries are used for local development of ElasticGraph applications, but are not intended to be deployed to production (except for elasticgraph-rack).
+elasticgraph-rack is used to boot ElasticGraph locally but can also be used to run ElasticGraph in any rack-compatible server (including a Rails application).
+
+
+
elasticgraph-local: Provides support for developing and running ElasticGraph applications locally.
+
elasticgraph-rack: ElasticGraph gem for serving an ElasticGraph GraphQL endpoint using rack.
+
elasticgraph-schema_definition: ElasticGraph gem that provides the schema definition API and generates schema artifacts.
+
+
+
Dependency Diagram
+
+
+
+
Versioning Policy
+
+
ElasticGraph does not strictly follow the SemVer spec. We followed that early in the project’s life
+cycle and realized that it obscures some important compatibility information.
+
+
ElasticGraph’s versioning policy is designed to communicate compatibility information related to the following stakeholders:
+
+
+
Application maintainers: engineers that define an ElasticGraph schema, maintain project configuration, and perform upgrades.
+
Data publishers: systems that publish data into an ElasticGraph application for ingestion by an ElasticGraph indexer.
+
GraphQL clients: clients of the GraphQL API of an ElasticGraph application.
+
+
+
We use the following versioning scheme:
+
+
+
Version numbers are in a 0.MAJOR.MINOR.PATCH format. (The 0. prefix is there in order to reserve 1.0.0 and all later versions
+for after ElasticGraph has been open-sourced).
+
Increments to the PATCH version indicate that the new release contains no backwards incompatibilities for any stakeholders.
+It may contain bug fixes, new features, internal refactorings, and dependency upgrades, among other things. You can expect that
+PATCH level upgrades are always safe–just update the version in your bundle, generate new schema artifacts, and you should be done.
+
Increments to the MINOR version indicate that the new release contains some backwards incompatibilities that may impact the
+application maintainers of some ElasticGraph applications. MINOR releases may include renames to configuration settings,
+changes to the schema definition API, and new schema definition requirements, among other things. You can expect that MINOR
+level upgrades can usually be done in 30 minutes or less (usually in a single commit!), with release notes and clear errors
+from ElasticGraph command line tasks providing guidance on how to upgrade.
+
Increments to the MAJOR version indicate that the new release contains some backwards incompatibilities that may impact the
+data publishers or GraphQL clients of some ElasticGraph applications. MAJOR releases may include changes to the GraphQL
+schema that require careful migration of GraphQL clients or changes to how indexing is done that require a dataset to be
+re-indexed from scratch (e.g. by having data publishers republish their data into an ElasticGraph indexer running the new
+version). You can expect that the release notes will include detailed instructions on how to perform a MAJOR version upgrade.
+
+
+
Deprecation warnings may be included at any of these levels–for example, a PATCH release may contain a deprecation warning
+for a breaking change that may impact application maintainers in an upcoming MINOR release, and a MINOR release may
+contain deprecation warnings for breaking changes that may impact data publishers or GraphQL clients in an upcoming
+MAJOR release.
+
+
Each version level is cumulative over the prior levels. That is, a MINOR release may include PATCH-level changes in addition
+to backwards incompatibilities that may impact application maintainers. A MAJOR release may include PATCH-level or
+MINOR-level changes in addition to backwards incompatibilities that may impact data publishers or GraphQL clients.
+
+
Note that this policy was first adopted in the v0.15.1.0 release. All prior releases aimed (with some occasional mistakes!)
+to follow SemVer with a 0.MAJOR.MINOR.PATCH versioning scheme.
+
+
Note that all gems in this repository share the same version number. Every time we cut a release, we increment the version
+for all gems and release all gems, even if a gem has had no changes since the last release. This is simpler to work with
+than the alternatives.
