From 9adc0b88d7820876722ebac73fb8884badad9b6e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jovan=20Kruni=C4=87?= Date: Thu, 25 Jul 2019 16:48:13 +0200 Subject: [PATCH] docs: add missing inline docs for elasticsearch related interfaces Closes #41 --- src/storage/elasticsearch/common.ts | 219 +++++++++++++++++++++++++++- 1 file changed, 215 insertions(+), 4 deletions(-) diff --git a/src/storage/elasticsearch/common.ts b/src/storage/elasticsearch/common.ts index faa99ce8..30ccee0a 100644 --- a/src/storage/elasticsearch/common.ts +++ b/src/storage/elasticsearch/common.ts @@ -17,10 +17,9 @@ import {SCThingType} from '@openstapps/core'; import {SCThing} from '@openstapps/core'; import {NameList} from 'elasticsearch'; -/* tslint:disable:completed-docs */ // TODO: document properties of interfaces /** * An elasticsearch bucket aggregation - * @see https://www.elastic.co/guide/en/elasticsearch/reference/5.5/search-aggregations-bucket.html + * @see https://www.elastic.co/guide/en/elasticsearch/reference/5.6/search-aggregations-bucket.html */ export interface AggregationSchema { [aggregationName: string]: ESTermsFilter; @@ -33,11 +32,39 @@ export interface AggregationSchema { * explanation of what the parameters mean */ export interface ElasticsearchQueryDisMaxConfig { + /** + * Relative (to a total number of documents) or absolute number to exclude meaningless matches that frequently appear + */ cutoffFrequency: number; + + /** + * The maximum allowed Levenshtein Edit Distance (or number of edits) + * @see https://www.elastic.co/guide/en/elasticsearch/reference/5.6/common-options.html#fuzziness + */ fuzziness: number; + + /** + * Increase the importance (relevance score) of a field + * @see https://www.elastic.co/guide/en/elasticsearch/reference/5.6/mapping-boost.html + */ matchBoosting: number; + + /** + * Minimal number (or percentage) of words that should match in a query + * @see https://www.elastic.co/guide/en/elasticsearch/reference/5.6/query-dsl-minimum-should-match.html + */ minMatch: string; + + /** + * Type of the query - in this case 'dis_max' which is a union of its subqueries + * @see https://www.elastic.co/guide/en/elasticsearch/reference/5.6/query-dsl-dis-max-query.html + */ queryType: 'dis_max'; + + /** + * Changes behavior of default calculation of the score when multiple results match + * @see https://www.elastic.co/guide/en/elasticsearch/reference/5.6/query-dsl-multi-match-query.html#tie-breaker + */ tieBreaker: number; } @@ -48,26 +75,83 @@ export interface ElasticsearchQueryDisMaxConfig { * explanation of what the parameters mean */ export interface ElasticsearchQueryQueryStringConfig { + /** + * Minimal number (or percentage) of words that should match in a query + * @see https://www.elastic.co/guide/en/elasticsearch/reference/5.6/query-dsl-minimum-should-match.html + */ minMatch: string; + + /** + * Type of the query - in this case 'query_string' which uses a query parser in order to parse content + * @see https://www.elastic.co/guide/en/elasticsearch/reference/5.6/query-dsl-query-string-query.html + */ queryType: 'query_string'; } /** * A hit in an elastiscsearch search result + * @see https://www.elastic.co/guide/en/elasticsearch/reference/5.6/mapping-fields.html */ export interface ElasticsearchObject { + /** + * Unique identifier of a document (object) + */ _id: string; + + /** + * The index to which the document belongs + */ _index: string; + + /** + * Relevancy of the document to a query + */ _score: number; + + /** + * The original JSON representing the body of the document + */ _source: T; + + /** + * The document's mapping type + * @see https://www.elastic.co/guide/en/elasticsearch/reference/5.6/mapping-type-field.html + */ _type: string; + + /** + * Version of the document + */ _version?: number; + + /** + * Used to index the same field in different ways for different purposes + * @see https://www.elastic.co/guide/en/elasticsearch/reference/5.6/multi-fields.html + */ fields?: NameList; - // tslint:disable: no-any + + /** + * Used to highlight search results on one or more fields + * @see https://www.elastic.co/guide/en/elasticsearch/reference/5.6/search-request-highlighting.html + */ + // tslint:disable-next-line: no-any highlight?: any; + + /** + * Used in when nested/children documents match the query + * @see https://www.elastic.co/guide/en/elasticsearch/reference/5.6/search-request-inner-hits.html + */ + // tslint:disable-next-line: no-any inner_hits?: any; - // tslint:enable: no-any + + /** + * Queries that matched for documents in results + */ matched_queries?: string[]; + + /** + * Sorting definition + */ sort?: string[]; } @@ -77,7 +161,13 @@ export interface ElasticsearchObject { * The config file extends the SCConfig file by further defining how the database property */ export interface ElasticsearchConfigFile { + /** + * Configuration that is not visible to clients + */ internal: { + /** + * Database configuration + */ database: ElasticsearchConfig; }; } @@ -86,8 +176,19 @@ export interface ElasticsearchConfigFile { * An elasticsearch configuration */ export interface ElasticsearchConfig { + /** + * Name of the database + */ name: 'elasticsearch'; + + /** + * Configuration for using queries + */ query?: ElasticsearchQueryDisMaxConfig | ElasticsearchQueryQueryStringConfig; + + /** + * Version of the used elasticsearch + */ version: string; } @@ -95,6 +196,9 @@ export interface ElasticsearchConfig { * An elasticsearch term filter */ export interface ESTermFilter { + /** + * Definition of a term to match + */ term: { [fieldName: string]: string; }; @@ -104,8 +208,18 @@ export interface ESTermFilter { * An elasticsearch terms filter */ export interface ESTermsFilter { + /** + * Terms filter definition + */ terms: { + /** + * Field to apply filter to + */ field: string; + + /** + * Number of results + */ size?: number; }; } @@ -114,7 +228,13 @@ export interface ESTermsFilter { * An elasticsearch type filter */ export interface ESTypeFilter { + /** + * Type filter definition + */ type: { + /** + * Type name (SCThingType) to filter with + */ value: SCThingType; }; } @@ -123,9 +243,19 @@ export interface ESTypeFilter { * Filter arguments for an elasticsearch geo distance filter */ export interface ESGeoDistanceFilterArguments { + /** + * The radius of the circle centred on the specified location + */ distance: string; [fieldName: string]: { + /** + * Latitute + */ lat: number; + + /** + * Longitude + */ lon: number; } | string; } @@ -134,16 +264,36 @@ export interface ESGeoDistanceFilterArguments { * An elasticsearch geo distance filter */ export interface ESGeoDistanceFilter { + /** + * @see ESGeoDistanceFilterArguments + */ geo_distance: ESGeoDistanceFilterArguments; } /** * Filter arguments for an elasticsearch boolean filter + * @see https://www.elastic.co/guide/en/elasticsearch/reference/5.6/query-dsl-bool-query.html */ export interface ESBooleanFilterArguments { + /** + * Minimal number (or percentage) of words that should match in a query + * @see https://www.elastic.co/guide/en/elasticsearch/reference/5.6/query-dsl-minimum-should-match.html + */ minimum_should_match?: number; + + /** + * The clause (query) must appear in matching documents and will contribute to the score. + */ must?: T[]; + + /** + * The clause (query) must not appear in the matching documents. + */ must_not?: T[]; + + /** + * The clause (query) should appear in the matching document. + */ should?: T[]; } @@ -151,16 +301,35 @@ export interface ESBooleanFilterArguments { * An elasticsearch boolean filter */ export interface ESBooleanFilter { + /** + * @see ESBooleanFilterArguments + */ bool: ESBooleanFilterArguments; } /** * An elasticsearch function score query + * @see https://www.elastic.co/guide/en/elasticsearch/reference/5.6/query-dsl-function-score-query.html */ export interface ESFunctionScoreQuery { + /** + * Function score definition + */ function_score: { + /** + * Functions that compute score for query results (documents) + * @see ESFunctionScoreQueryFunction + */ functions: ESFunctionScoreQueryFunction[]; + + /** + * @see ESBooleanFilter + */ query: ESBooleanFilter; + + /** + * Specifies how the computed scores are combined + */ score_mode: 'multiply'; }; } @@ -169,7 +338,14 @@ export interface ESFunctionScoreQuery { * An function for an elasticsearch functions score query */ export interface ESFunctionScoreQueryFunction { + /** + * Function is applied only if a document matches the given filtering query + */ filter: ESTermFilter | ESTypeFilter | ESBooleanFilter; + + /** + * Weight (importance) of the filter + */ weight: number; } @@ -184,11 +360,29 @@ export interface ESDucetSort { * Sort arguments for an elasticsearch geo distance sort */ export interface ESGeoDistanceSortArguments { + /** + * What value to pick for sorting + */ mode: 'avg' | 'max' | 'median' | 'min'; + + /** + * Order + */ order: 'asc' | 'desc'; + + /** + * Value unit + */ unit: 'm'; [field: string]: { + /** + * Latitute + */ lat: number; + + /** + * Longitude + */ lon: number; } | string; } @@ -197,6 +391,9 @@ export interface ESGeoDistanceSortArguments { * An elasticsearch geo distance sort */ export interface ESGeoDistanceSort { + /** + * @see ESGeoDistanceFilterArguments + */ _geo_distance: ESGeoDistanceSortArguments; } @@ -204,9 +401,23 @@ export interface ESGeoDistanceSort { * An elasticsearch script sort */ export interface ScriptSort { + /** + * A script + */ _script: { + /** + * Order + */ order: 'asc' | 'desc'; + + /** + * The custom script used for sorting + */ script: string; + + /** + * What type is being sorted + */ type: 'number' | 'string'; }; }