openstapps/src/storage/elasticsearch/common.ts

/*
 * Copyright (C) 2019 StApps
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License as
 * published by the Free Software Foundation, either version 3 of the
 * License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Affero General Public License for more details.
 *
 * You should have received a copy of the GNU Affero General Public License
 * along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
import { SCThingTypes } from '@openstapps/core';
import { SCThing } from '@openstapps/core';

/**
 * An elasticsearch bucket aggregation
 * @see https://www.elastic.co/guide/en/elasticsearch/reference/5.5/search-aggregations-bucket.html
 */
export interface AggregationSchema {
  [aggregationName: string]: ESTermsFilter;
}

/**
 * A configuration for using the Dis Max Query
 *
 * See https://www.elastic.co/guide/en/elasticsearch/reference/5.5/query-dsl-dis-max-query.html for further
 * explanation of what the parameters mean
 */
export interface ElasticsearchQueryDisMaxConfig {
  cutoffFrequency: number;
  fuzziness: number;
  matchBoosting: number;
  minMatch: string;
  queryType: 'dis_max';
  tieBreaker: number;
}

/**
 * A configuration for using Query String Query
 *
 * See https://www.elastic.co/guide/en/elasticsearch/reference/5.5/query-dsl-query-string-query.html for further
 * explanation of what the parameters mean
 */
export interface ElasticsearchQueryQueryStringConfig {
  minMatch: string;
  queryType: 'query_string';
}

/**
 * A hit in an elastiscsearch search result
 */
export interface ElasticsearchObject<T extends SCThing> {
  _id: string;
  _index: string;
  _score: number;
  _source: T;
  _type: string;
  _version?: number;
  fields?: any;
  highlight?: any;
  inner_hits?: any;
  matched_queries?: string[];
  sort?: string[];
}

/**
 * An config file for the elasticsearch database interface
 *
 * The config file extends the SCConfig file by further defining how the database property
 */
export interface ElasticsearchConfigFile {
  internal: {
    database: ElasticsearchConfig;
  };
}

/**
 * An elasticsearch configuration
 */
export interface ElasticsearchConfig {
  name: 'elasticsearch';
  query?: ElasticsearchQueryDisMaxConfig | ElasticsearchQueryQueryStringConfig;
  version: string;
}

/**
 * An elasticsearch term filter
 */
export interface ESTermFilter {
  term: {
    [fieldName: string]: string;
  };
}

/**
 * An elasticsearch terms filter
 */
export interface ESTermsFilter {
  terms: {
    field: string;
    size?: number;
  };
}

/**
 * An elasticsearch type filter
 */
export interface ESTypeFilter {
  type: {
    value: SCThingTypes;
  };
}

/**
 * Filter arguments for an elasticsearch geo distance filter
 */
export interface ESGeoDistanceFilterArguments {
  distance: string;
  [fieldName: string]: {
    lat: number;
    lon: number;
  } | string;
}

/**
 * An elasticsearch geo distance filter
 */
export interface ESGeoDistanceFilter {
  geo_distance: ESGeoDistanceFilterArguments;
}

/**
 * Filter arguments for an elasticsearch boolean filter
 */
export interface ESBooleanFilterArguments<T> {
  minimum_should_match?: number;
  must?: T[];
  must_not?: T[];
  should?: T[];
}

/**
 * An elasticsearch boolean filter
 */
export interface ESBooleanFilter<T> {
  bool: ESBooleanFilterArguments<T>;
}

/**
 * An elasticsearch function score query
 */
export interface ESFunctionScoreQuery {
  function_score: {
    functions: ESFunctionScoreQueryFunction[];
    query: ESBooleanFilter<any>;
    score_mode: 'multiply';
  };
}

/**
 * An function for an elasticsearch functions score query
 */
export interface ESFunctionScoreQueryFunction {
  filter: ESTermFilter | ESTypeFilter | ESBooleanFilter<ESTermFilter | ESTypeFilter>;
  weight: number;
}

/**
 * An elasticsearch ducet sort
 */
export interface ESDucetSort {
  [field: string]: string;
}

/**
 * Sort arguments for an elasticsearch geo distance sort
 */
export interface ESGeoDistanceSortArguments {
  mode: 'avg' | 'max' | 'median' | 'min';
  order: 'asc' | 'desc';
  unit: 'm';
  [field: string]: {
    lat: number;
    lon: number;
  } | string;
}

/**
 * An elasticsearch geo distance sort
 */
export interface ESGeoDistanceSort {
  _geo_distance: ESGeoDistanceSortArguments;
}

/**
 * An elasticsearch script sort
 */
export interface ScriptSort {
  _script: {
    order: 'asc' | 'desc';
    script: string;
    type: 'number' | 'string';
  };
}