@cognite/sdk-beta - npm Package Compare versions

Comparing version 1.1.3 to 1.2.0

CHANGELOG.md

@@ -6,2 +6,13 @@ # Change Log
 
+# [1.2.0](https://github.com/cognitedata/cognite-sdk-js/compare/@cognite/sdk-beta@1.1.3...@cognite/sdk-beta@1.2.0) (2020-11-25)
+
+
+### Features
+
+* **contextualization:** entity matching API ([9609226](https://github.com/cognitedata/cognite-sdk-js/commit/960922642188898c1eee160b304d0fcf57c9661e))
+
+
+
+
+
 ## [1.1.3](https://github.com/cognitedata/cognite-sdk-js/compare/@cognite/sdk-beta@1.1.2...@cognite/sdk-beta@1.1.3) (2020-11-18)
@@ -8,0 +19,0 @@

dist/index.js

@@ -37,5 +37,204 @@ 'use strict';
 
-var version="1.1.3";
+function __awaiter(thisArg, _arguments, P, generator) {
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : new P(function (resolve) { resolve(result.value); }).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+}
 
+function __generator(thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
+    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (_) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+}
+
+var version="1.2.0";
+
 // Copyright 2020 Cognite AS
+var EntityMatchingApi = /** @class */ (function (_super) {
+    __extends(EntityMatchingApi, _super);
+    function EntityMatchingApi() {
+        var _this = _super !== null && _super.apply(this, arguments) || this;
+        /**
+         * [Create entity matcher](https://docs.cognite.com/api/v1/#operation/entityMatchingCreate)
+         *
+         * ```js
+         * const result = await client.entityMatching.create({
+         *  sources: [{externalId: 'asset1', name: 'asset1'}, {externalId: 'asset2', name: 'asset2'}],
+         *  targets: [{externalId: 'ts1', name: 'ts1'}, {externalId: 'ts2', name: 'ts2'}],
+         *  externalId: 'model123',
+         *  name: 'model123',
+         * });
+         * ```
+         */
+        _this.create = function (scope) { return __awaiter(_this, void 0, void 0, function () {
+            var path, response;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        path = this.url();
+                        return [4 /*yield*/, this.post(path, {
+                                data: scope,
+                            })];
+                    case 1:
+                        response = _a.sent();
+                        return [2 /*return*/, this.addToMapAndReturn(response.data, response)];
+                }
+            });
+        }); };
+        /**
+         * [Retrieve entity matching models](https://docs.cognite.com/api/v1/#operation/entityMatchingRetrive)
+         *
+         * ```js
+         * const [result] = await client.entityMatching.retrieve([{ externalId: 'model123' }]);
+         * ```
+         */
+        _this.retrieve = function (ids) {
+            return _super.prototype.retrieveEndpoint.call(_this, ids);
+        };
+        /**
+         * [List entity matching models](https://docs.cognite.com/api/v1/#operation/entityMatchingFilter)
+         *
+         * ```js
+         * const { items } = await client.entityMatching.list({ filter: { name: 'model123' }});
+         * ```
+         */
+        _this.list = function (scope) {
+            return _super.prototype.listEndpoint.call(_this, _this.callListEndpointWithPost, scope);
+        };
+        /**
+         * [Update entity matching models](https://docs.cognite.com/api/v1/#operation/entityMatchingUpdate)
+         *
+         * ```js
+         * const [updated] = await client.entityMatching.update([{
+         *  externalId: 'model123',
+         *  update: { description: { set: 'ø' }}
+         * }]);
+         * ```
+         */
+        _this.update = function (changes) {
+            return _super.prototype.updateEndpoint.call(_this, changes);
+        };
+        /**
+         * [Delete entity matcher model](https://docs.cognite.com/api/v1/#operation/entityMatchingDelete)
+         *
+         * ```js
+         * await client.entityMatching.delete([{ externalId: 'model123' }]);
+         * ```
+         */
+        _this.delete = function (ids) { return __awaiter(_this, void 0, void 0, function () {
+            return __generator(this, function (_a) {
+                return [2 /*return*/, _super.prototype.deleteEndpoint.call(this, ids)];
+            });
+        }); };
+        /**
+         * [Predict matches](https://docs.cognite.com/api/v1/#operation/entityMatchingPredict)
+         *
+         * ```js
+         * const response = await client.entityMatching.predict({
+         *  externalId: 'model123',
+         *  sources: [{externalId: 'asset1', name: 'asset1'}, {externalId: 'asset2', name: 'asset2'}],
+         *  targets: [{externalId: 'ts1', name: 'ts1'}, {externalId: 'ts2', name: 'ts2'}],
+         * });
+         * ```
+         */
+        _this.predict = function (scope) { return __awaiter(_this, void 0, void 0, function () {
+            var path, response;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        path = this.url('predict');
+                        return [4 /*yield*/, this.post(path, {
+                                data: scope,
+                            })];
+                    case 1:
+                        response = _a.sent();
+                        return [2 /*return*/, this.addToMapAndReturn(response.data, response)];
+                }
+            });
+        }); };
+        /**
+         * [Retrieve entity matcher predict result](https://docs.cognite.com/api/playground/#operation/entityMatchingPredictResults)
+         *
+         * ```js
+         * const { status, items } = await client.entityMatching.predictResult(12345678);
+         * ```
+         */
+        _this.predictResult = function (jobId) { return __awaiter(_this, void 0, void 0, function () {
+            var path, response;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        path = this.url("jobs/" + jobId);
+                        return [4 /*yield*/, this.get(path)];
+                    case 1:
+                        response = _a.sent();
+                        return [2 /*return*/, this.addToMapAndReturn(response.data, response)];
+                }
+            });
+        }); };
+        /**
+         * [Re-fit entity matcher model](https://docs.cognite.com/api/v1/#operation/entityMatchingReFit)
+         *
+         * ```js
+         * await client.entityMatching.refit({
+         *  newExternalId: 'newModel123',
+         *  sources: [{externalId: 'asset1', name: 'asset1'}, {externalId: 'asset2', name: 'asset2'}],
+         *  targets: [{externalId: 'ts1', name: 'ts1'}, {externalId: 'ts2', name: 'ts2'}],
+         *  externalId: 'model123',
+         *  trueMatches: [{sourceExternalId: 'asset1', targetExternalId: 'ts1'}]
+         * });
+         * ```
+         */
+        _this.refit = function (scope) { return __awaiter(_this, void 0, void 0, function () {
+            var path, response;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        path = this.url('refit');
+                        return [4 /*yield*/, this.post(path, {
+                                data: scope,
+                            })];
+                    case 1:
+                        response = _a.sent();
+                        return [2 /*return*/, this.addToMapAndReturn(response.data, response)];
+                }
+            });
+        }); };
+        return _this;
+    }
+    /**
+     * @hidden
+     */
+    EntityMatchingApi.prototype.getDateProps = function () {
+        return this.pickDateProps(['items'], ['createdTime', 'startTime', 'statusTime']);
+    };
+    return EntityMatchingApi;
+}(sdkCore.BaseResourceAPI));
+
+// Copyright 2020 Cognite AS
 var RelationshipsApi = /** @class */ (function (_super) {
@@ -144,2 +343,9 @@ __extends(RelationshipsApi, _super);
     });
+    Object.defineProperty(CogniteClient.prototype, "entityMatching", {
+        get: function () {
+            return sdkCore.accessApi(this.entityMatchingApi);
+        },
+        enumerable: false,
+        configurable: true
+    });
     Object.defineProperty(CogniteClient.prototype, "version", {
@@ -155,2 +361,3 @@ get: function () {
         this.relationshipsApi = this.apiFactory(RelationshipsApi, 'relationships');
+        this.entityMatchingApi = this.apiFactory(EntityMatchingApi, 'context/entitymatching');
     };
@@ -160,2 +367,24 @@ return CogniteClient;
 
+// Copyright 2020 Cognite AS
+var ContextJobStatus = {
+    QUEUED: 'QUEUED',
+    RUNNING: 'RUNNING',
+    COMPLETED: 'COMPLETED',
+    FAILED: 'FAILED',
+};
+var EntityMatchingFeatureType = {
+    SIMPLE: 'simple',
+    BIGRAM: 'bigram',
+    FREQUENCY_WEIGHTED_BIGRAM: 'frequencyweightedbigram',
+    BIGRAM_EXTRA_TOKENIZERS: 'bigramextratokenizers',
+    BIGRAM_COMBO: 'bigramcombo',
+};
+var EntityMatchingClassifier = {
+    RANDOM_FOREST: 'randomforest',
+    DECISION_TREE: 'decisiontree',
+    LOGISTIC_REGRESSION: 'logisticregression',
+    AUGMENTED_LOGISTIC_REGRESSION: 'augmentedlogisticregression',
+    AUGMENTED_RANDOM_FOREST: 'augmentedrandomforest',
+};
+
 Object.keys(sdk).forEach(function (k) {
@@ -165,3 +394,6 @@ if (k !== 'default') exports[k] = sdk[k];
 exports.CogniteClient = CogniteClient;
+exports.ContextJobStatus = ContextJobStatus;
+exports.EntityMatchingClassifier = EntityMatchingClassifier;
+exports.EntityMatchingFeatureType = EntityMatchingFeatureType;
 exports.RelationshipsApi = RelationshipsApi;
 //# sourceMappingURL=index.js.map

dist/src/cogniteClient.d.ts

 import { ClientOptions, CogniteClient as CogniteClientStable } from '@cognite/sdk';
+import { EntityMatchingApi } from './api/entityMatching/entityMatchingApi';
 import { RelationshipsApi } from './api/relationships/relationshipsApi';
@@ -7,2 +8,3 @@ declare class CogniteClientCleaned extends CogniteClientStable {
     private relationshipsApi?;
+    private entityMatchingApi?;
     /**
@@ -27,2 +29,3 @@ * Create a new SDK client (beta)
     get relationships(): RelationshipsApi;
+    get entityMatching(): EntityMatchingApi;
     protected get version(): string;
@@ -29,0 +32,0 @@ protected initAPIs(): void;

dist/src/types.d.ts

@@ -1,2 +0,2 @@
-import { CogniteExternalId, CogniteInternalId, CreatedAndLastUpdatedTimeFilter, DateRange, FilterQuery, IdEither, Label, Timestamp, Range, LabelFilter, CreatedAndLastUpdatedTime } from '@cognite/sdk';
+import { CogniteExternalId, CogniteInternalId, CreatedAndLastUpdatedTimeFilter, DateRange, FilterQuery, IdEither, Label, Timestamp, Range, LabelFilter, SinglePatchString, CreatedAndLastUpdatedTime } from '@cognite/sdk';
 export declare type RelationshipResourceType = 'asset' | 'timeSeries' | 'file' | 'event' | 'sequence';
@@ -108,1 +108,307 @@ export interface ExternalRelationship {
 }
+export declare type ContextJobStatus = 'QUEUED' | 'RUNNING' | 'COMPLETED' | 'FAILED';
+export declare const ContextJobStatus: {
+    QUEUED: ContextJobStatus;
+    RUNNING: ContextJobStatus;
+    COMPLETED: ContextJobStatus;
+    FAILED: ContextJobStatus;
+};
+/**
+ * Contextualization job ID.
+ */
+export declare type ContextJobId = number;
+export interface EntityMatchingResponseBase {
+    /**
+     * User defined name of the model.
+     */
+    name: string;
+    /**
+     * User defined description of the model
+     */
+    description: string;
+    /**
+     * The status of the job.
+     */
+    status: ContextJobStatus;
+    createdTime: Date;
+    startTime: Date;
+    statusTime: Date;
+}
+export interface ExternalEntityToMatch {
+    id?: CogniteInternalId;
+    externalId?: CogniteExternalId;
+    [key: string]: string | number | undefined;
+}
+export declare type EntityMatchingFeatureType = 'simple' | 'bigram' | 'frequencyweightedbigram' | 'bigramextratokenizers' | 'bigramcombo';
+export declare const EntityMatchingFeatureType: {
+    SIMPLE: EntityMatchingFeatureType;
+    BIGRAM: EntityMatchingFeatureType;
+    FREQUENCY_WEIGHTED_BIGRAM: EntityMatchingFeatureType;
+    BIGRAM_EXTRA_TOKENIZERS: EntityMatchingFeatureType;
+    BIGRAM_COMBO: EntityMatchingFeatureType;
+};
+export declare type EntityMatchingClassifier = 'randomforest' | 'decisiontree' | 'logisticregression' | 'augmentedlogisticregression' | 'augmentedrandomforest';
+export declare const EntityMatchingClassifier: {
+    RANDOM_FOREST: EntityMatchingClassifier;
+    DECISION_TREE: EntityMatchingClassifier;
+    LOGISTIC_REGRESSION: EntityMatchingClassifier;
+    AUGMENTED_LOGISTIC_REGRESSION: EntityMatchingClassifier;
+    AUGMENTED_RANDOM_FOREST: EntityMatchingClassifier;
+};
+export interface EntityMatchingField {
+    from: string;
+    to: string;
+}
+export declare type ExternalEntityTrueMatch = ExternalEntityTrueMatchSource & ExternalEntityTrueMatchTarget;
+declare type ExternalEntityTrueMatchSource = {
+    /**
+     * The id for the source object of the match.
+     */
+    sourceId: CogniteInternalId;
+} | {
+    /**
+     * The external id for the source object of the match.
+     */
+    sourceExternalId: CogniteExternalId;
+};
+declare type ExternalEntityTrueMatchTarget = {
+    /**
+     * The id for the target object of the match.
+     */
+    targetId: CogniteInternalId;
+} | {
+    /**
+     * The external id for the target object of the match.
+     */
+    targetExternalId: CogniteExternalId;
+};
+export interface EntityMatchingCreateRequest {
+    /**
+     * List of custom source object to match from, for example, time series. String key -> value. Only string values are considered in the matching. Optional id and/or externalId fields.
+     */
+    sources: ExternalEntityToMatch[];
+    /**
+     * List of custom target object to match to, for example, assets. String key -> value. Only string values are considered in the matching. Optional id and/or externalId fields.
+     */
+    targets: ExternalEntityToMatch[];
+    /**
+     * List of objects of pairs of fromId or fromExternalId and toId or toExternalId, that corresponds to entities in matchFrom and matchTo respectively, that indicates a confirmed match used to train the model. If omitted, an unsupervised model is used.
+     */
+    trueMatches?: ExternalEntityTrueMatch[];
+    externalId?: CogniteExternalId;
+    /**
+     * User defined name of the model.
+     */
+    name?: string;
+    /**
+     * User defined description of the model.
+     */
+    description?: string;
+    /**
+     * List of pairs of fields from the target and source items used to calculate features. All source and target items should have all the source and target fields specified here.
+     */
+    matchFields?: EntityMatchingField[];
+    /**
+     * Defines the combination of features used. The options are:
+     * Simple: Calculates a single cosine-distance similarity score for each of the fields defined in keysFromTo. This is the fastest option.
+     * Bigram: Adds similarity score based on the sequence of the terms.
+     * Frequency-Weighted-Bigram: Calculates a similarity score based on the sequence of the terms, giving higher weights to less commonly occurring tokens.
+     * Bigram-Extra-Tokenizers: Similar to bigram, but able to learn that leading zeros and spaces should be ignored in matching.
+     * Bigram-Combo: Calculates all of the above options, relying on the model to determine the appropriate features to use. This is the slowest option.
+     */
+    featureType?: EntityMatchingFeatureType;
+    /**
+     * The classifier used in the model. Only relevant if there are trueMatches/labeled data and a supervised  model is fitted.
+     */
+    classifier?: EntityMatchingClassifier;
+    /**
+     * If True, replaces missing fields in `sources` or `targets` entities, for fields set in set in `matchFields`, with empty strings. Else, returns an error if there are missing data.
+     */
+    ignoreMissingFields?: boolean;
+}
+export interface EntityMatchingCreateResponse extends EntityMatchingResponseBase {
+    id: CogniteInternalId;
+    externalId: CogniteExternalId;
+    /**
+     * Defines the combination of features used in the entity matcher model.
+     */
+    featureType?: EntityMatchingFeatureType;
+    /**
+     * Name of the classifier used in the model, "Unsupervised" if unsupervised model.
+     */
+    classifier?: EntityMatchingClassifier;
+    /**
+     * If True, missing fields in sources or targets entities set in matchFields, are replaced with empty strings.
+     */
+    ignoreMissingFields?: boolean;
+    /**
+     * List of pairs of fields from the target and source items used to calculate features. All source and target items should have all the source and target fields specified here.
+     */
+    matchFields?: EntityMatchingField[];
+    /**
+     * The ID of original model, only relevant when the model is a retrained model.
+     */
+    originalId?: CogniteInternalId;
+}
+export interface EntityMatchingModel extends EntityMatchingResponseBase {
+    id: CogniteInternalId;
+    externalId: CogniteExternalId;
+    /**
+     * Defines the combination of features used in the entity matcher model.
+     */
+    featureType?: EntityMatchingFeatureType;
+    /**
+     * Name of the classifier used in the model, "Unsupervised" if unsupervised model.
+     */
+    classifier?: EntityMatchingClassifier;
+    /**
+     * Array of objects (MatchFields) List of pairs of fields from the target and source items used to calculate features. All source and target items should have all the source and target fields specified here.
+     */
+    matchFields?: EntityMatchingField[];
+    /**
+     * The ID of original model, only relevant when the model is a retrained model.
+     */
+    originalId?: number;
+}
+export declare type EntityMatchingChange = IdEither & EntityMatchingPatch;
+export interface EntityMatchingPatch {
+    update: {
+        /**
+         * Set a new value for the model name.
+         */
+        name?: SinglePatchString;
+        /**
+         * Set a new value for the model description.
+         */
+        description: SinglePatchString;
+    };
+}
+export declare type EntityMatchingPredictRequest = IdEither & EntityMatchingPredictRequestBase;
+interface EntityMatchingPredictRequestBase {
+    /**
+     * List of source entities to predict matches for, for example, time series. If omitted, will use data source fit.
+     */
+    sources?: ExternalEntityToMatch[];
+    /**
+     * LList of potential target entities to match to one or more of the source entities, for example, assets. If omitted, will use data from fit.
+     */
+    targets?: ExternalEntityToMatch[];
+    /**
+     * The maximum number of results to return for each matchFrom.
+     */
+    numMatches?: number;
+    /**
+     * Only return matches with score above this threshold.
+     */
+    scoreThreshold?: number;
+}
+export interface EntityMatchingPredictResponse extends EntityMatchingResponseBase {
+    /**
+     * Contextualization job ID.
+     */
+    jobId: number;
+}
+export declare type EntityMatchingRefitRequest = IdEither & EntityMatchingRefitRequestBase;
+interface EntityMatchingRefitRequestBase {
+    /**
+     * External ID for the new refitted model provided by client. Should be unique within the project.
+     */
+    newExternalId?: CogniteExternalId;
+    /**
+     * List of additional confirmed matches used to train the model. The new model uses a combination of this and trueMatches from the orginal model. If there are identical match-from ids, the pair from the original model is dropped.
+     */
+    trueMatches: ExternalEntityTrueMatch[];
+    /**
+     * List of source entities, for example, time series. If omitted, will use data from fit.
+     */
+    sources?: ExternalEntityToMatch[];
+    /**
+     * List of target entities, for example, assets. If omitted, will use data from fit.
+     */
+    targets?: ExternalEntityToMatch[];
+}
+export interface EntityMatchingRefitResponse extends EntityMatchingResponseBase {
+    id: CogniteInternalId;
+    externalId: CogniteExternalId;
+    /**
+     * Defines the combination of features used in the entity matcher model.
+     */
+    featureType: EntityMatchingFeatureType;
+    /**
+     * Name of the classifier used in the model, "Unsupervised" if unsupervised model.
+     */
+    classifier: EntityMatchingClassifier;
+    /**
+     * If True, missing fields in sources or targets entities set in matchFields, are replaced with empty strings.
+     */
+    ignoreMissingFields?: boolean;
+    /**
+     * List of pairs of fields from the target and source items used to calculate features. All source and target items should have all the source and target fields specified here.
+     */
+    matchFields?: EntityMatchingField[];
+    /**
+     * The ID of original model, only relevant when the model is a retrained model.
+     */
+    originalId: CogniteInternalId;
+}
+export interface EntityMatchingPredictions {
+    jobId: ContextJobId;
+    /**
+     * The status of the job.
+     */
+    status: ContextJobStatus;
+    /**
+     * List of matched entities with confidence score.
+     */
+    items: EntityMatchingPrediction[];
+}
+export interface EntityMatchingPrediction {
+    /**
+     * The matchFrom item given to predict.
+     */
+    matchFrom: ExternalEntityToMatch;
+    /**
+     * Matched items, sorted from highest score to lowest. May be empty.
+     */
+    matches: EntityMatchingPredictedItem[];
+}
+export interface EntityMatchingPredictedItem {
+    /**
+     * The matchTo item given to predict.
+     */
+    matchTo: ExternalEntityToMatch;
+    /**
+     * The model's confidence in the match.
+     */
+    score: number;
+}
+export interface EntityMatchingFilter {
+    /**
+     * User defined name of the model.
+     */
+    name?: string;
+    /**
+     * User defined description of the model.
+     */
+    description?: string;
+    /**
+     * The feature type used to fit the model.
+     */
+    featureType?: EntityMatchingFeatureType;
+    /**
+     * Name of the classifier supervised model, "Unsupervised" if unsupervised model
+     */
+    classifier?: string;
+    /**
+     * List of pairs of fields from the matchTo and matchFrom items used to create features.
+     */
+    matchFields?: EntityMatchingField[];
+    /**
+     * The ID of original model, only relevant when the model is a retrained model.
+     */
+    originalModelId?: CogniteInternalId;
+}
+export interface EntityMatchingFilterRequest extends FilterQuery {
+    filter?: EntityMatchingFilter;
+}
+export {};

package.json

@@ -9,3 +9,3 @@ {
   "types": "dist/src/index.d.js",
-  "version": "1.1.3",
+  "version": "1.2.0",
   "scripts": {
@@ -32,3 +32,3 @@ "clean": "rm -rf dist/ docs/ codeSnippets/",
   },
-  "gitHead": "233bf8cb7293a8a3a3a5ddc578cd442aca00c0aa"
+  "gitHead": "40855ee7f0ac7b939859708f93f1fcd8ea190d3c"
 }

src/cogniteClient.ts

@@ -9,2 +9,3 @@ // Copyright 2020 Cognite AS
 import { version } from '../package.json';
+import { EntityMatchingApi } from './api/entityMatching/entityMatchingApi';
 import { RelationshipsApi } from './api/relationships/relationshipsApi';
@@ -18,2 +19,3 @@
   private relationshipsApi?: RelationshipsApi;
+  private entityMatchingApi?: EntityMatchingApi;
 
@@ -45,2 +47,6 @@ /**
 
+  public get entityMatching() {
+    return accessApi(this.entityMatchingApi);
+  }
+
   protected get version() {
@@ -54,3 +60,7 @@ return `${version}-beta`;
     this.relationshipsApi = this.apiFactory(RelationshipsApi, 'relationships');
+    this.entityMatchingApi = this.apiFactory(
+      EntityMatchingApi,
+      'context/entitymatching'
+    );
   }
 }

src/types.ts

@@ -14,2 +14,3 @@ // Copyright 2020 Cognite AS
   LabelFilter,
+  SinglePatchString,
   CreatedAndLastUpdatedTime,
@@ -137,1 +138,355 @@ } from '@cognite/sdk';
 }
+
+export type ContextJobStatus = 'QUEUED' | 'RUNNING' | 'COMPLETED' | 'FAILED';
+
+export const ContextJobStatus = {
+  QUEUED: 'QUEUED' as ContextJobStatus,
+  RUNNING: 'RUNNING' as ContextJobStatus,
+  COMPLETED: 'COMPLETED' as ContextJobStatus,
+  FAILED: 'FAILED' as ContextJobStatus,
+};
+
+/**
+ * Contextualization job ID.
+ */
+export type ContextJobId = number;
+
+export interface EntityMatchingResponseBase {
+  /**
+   * User defined name of the model.
+   */
+  name: string;
+  /**
+   * User defined description of the model
+   */
+  description: string;
+  /**
+   * The status of the job.
+   */
+  status: ContextJobStatus;
+  createdTime: Date;
+  startTime: Date;
+  statusTime: Date;
+}
+
+export interface ExternalEntityToMatch {
+  id?: CogniteInternalId;
+  externalId?: CogniteExternalId;
+  [key: string]: string | number | undefined;
+}
+
+export type EntityMatchingFeatureType =
+  | 'simple'
+  | 'bigram'
+  | 'frequencyweightedbigram'
+  | 'bigramextratokenizers'
+  | 'bigramcombo';
+
+export const EntityMatchingFeatureType = {
+  SIMPLE: 'simple' as EntityMatchingFeatureType,
+  BIGRAM: 'bigram' as EntityMatchingFeatureType,
+  FREQUENCY_WEIGHTED_BIGRAM: 'frequencyweightedbigram' as EntityMatchingFeatureType,
+  BIGRAM_EXTRA_TOKENIZERS: 'bigramextratokenizers' as EntityMatchingFeatureType,
+  BIGRAM_COMBO: 'bigramcombo' as EntityMatchingFeatureType,
+};
+
+export type EntityMatchingClassifier =
+  | 'randomforest'
+  | 'decisiontree'
+  | 'logisticregression'
+  | 'augmentedlogisticregression'
+  | 'augmentedrandomforest';
+
+export const EntityMatchingClassifier = {
+  RANDOM_FOREST: 'randomforest' as EntityMatchingClassifier,
+  DECISION_TREE: 'decisiontree' as EntityMatchingClassifier,
+  LOGISTIC_REGRESSION: 'logisticregression' as EntityMatchingClassifier,
+  AUGMENTED_LOGISTIC_REGRESSION: 'augmentedlogisticregression' as EntityMatchingClassifier,
+  AUGMENTED_RANDOM_FOREST: 'augmentedrandomforest' as EntityMatchingClassifier,
+};
+
+export interface EntityMatchingField {
+  from: string;
+  to: string;
+}
+
+export type ExternalEntityTrueMatch = ExternalEntityTrueMatchSource &
+  ExternalEntityTrueMatchTarget;
+
+type ExternalEntityTrueMatchSource =
+  | {
+      /**
+       * The id for the source object of the match.
+       */
+      sourceId: CogniteInternalId;
+    }
+  | {
+      /**
+       * The external id for the source object of the match.
+       */
+      sourceExternalId: CogniteExternalId;
+    };
+
+type ExternalEntityTrueMatchTarget =
+  | {
+      /**
+       * The id for the target object of the match.
+       */
+      targetId: CogniteInternalId;
+    }
+  | {
+      /**
+       * The external id for the target object of the match.
+       */
+      targetExternalId: CogniteExternalId;
+    };
+
+export interface EntityMatchingCreateRequest {
+  /**
+   * List of custom source object to match from, for example, time series. String key -> value. Only string values are considered in the matching. Optional id and/or externalId fields.
+   */
+  sources: ExternalEntityToMatch[];
+  /**
+   * List of custom target object to match to, for example, assets. String key -> value. Only string values are considered in the matching. Optional id and/or externalId fields.
+   */
+  targets: ExternalEntityToMatch[];
+  /**
+   * List of objects of pairs of fromId or fromExternalId and toId or toExternalId, that corresponds to entities in matchFrom and matchTo respectively, that indicates a confirmed match used to train the model. If omitted, an unsupervised model is used.
+   */
+  trueMatches?: ExternalEntityTrueMatch[];
+  externalId?: CogniteExternalId;
+  /**
+   * User defined name of the model.
+   */
+  name?: string;
+  /**
+   * User defined description of the model.
+   */
+  description?: string;
+  /**
+   * List of pairs of fields from the target and source items used to calculate features. All source and target items should have all the source and target fields specified here.
+   */
+  matchFields?: EntityMatchingField[];
+  /**
+   * Defines the combination of features used. The options are:
+   * Simple: Calculates a single cosine-distance similarity score for each of the fields defined in keysFromTo. This is the fastest option.
+   * Bigram: Adds similarity score based on the sequence of the terms.
+   * Frequency-Weighted-Bigram: Calculates a similarity score based on the sequence of the terms, giving higher weights to less commonly occurring tokens.
+   * Bigram-Extra-Tokenizers: Similar to bigram, but able to learn that leading zeros and spaces should be ignored in matching.
+   * Bigram-Combo: Calculates all of the above options, relying on the model to determine the appropriate features to use. This is the slowest option.
+   */
+  featureType?: EntityMatchingFeatureType;
+  /**
+   * The classifier used in the model. Only relevant if there are trueMatches/labeled data and a supervised  model is fitted.
+   */
+  classifier?: EntityMatchingClassifier;
+  /**
+   * If True, replaces missing fields in `sources` or `targets` entities, for fields set in set in `matchFields`, with empty strings. Else, returns an error if there are missing data.
+   */
+  ignoreMissingFields?: boolean;
+}
+
+export interface EntityMatchingCreateResponse
+  extends EntityMatchingResponseBase {
+  id: CogniteInternalId;
+  externalId: CogniteExternalId;
+  /**
+   * Defines the combination of features used in the entity matcher model.
+   */
+  featureType?: EntityMatchingFeatureType;
+  /**
+   * Name of the classifier used in the model, "Unsupervised" if unsupervised model.
+   */
+  classifier?: EntityMatchingClassifier;
+  /**
+   * If True, missing fields in sources or targets entities set in matchFields, are replaced with empty strings.
+   */
+  ignoreMissingFields?: boolean;
+  /**
+   * List of pairs of fields from the target and source items used to calculate features. All source and target items should have all the source and target fields specified here.
+   */
+  matchFields?: EntityMatchingField[];
+  /**
+   * The ID of original model, only relevant when the model is a retrained model.
+   */
+  originalId?: CogniteInternalId;
+}
+
+export interface EntityMatchingModel extends EntityMatchingResponseBase {
+  id: CogniteInternalId;
+  externalId: CogniteExternalId;
+  /**
+   * Defines the combination of features used in the entity matcher model.
+   */
+  featureType?: EntityMatchingFeatureType;
+  /**
+   * Name of the classifier used in the model, "Unsupervised" if unsupervised model.
+   */
+  classifier?: EntityMatchingClassifier;
+  /**
+   * Array of objects (MatchFields) List of pairs of fields from the target and source items used to calculate features. All source and target items should have all the source and target fields specified here.
+   */
+  matchFields?: EntityMatchingField[];
+  /**
+   * The ID of original model, only relevant when the model is a retrained model.
+   */
+  originalId?: number;
+}
+
+export type EntityMatchingChange = IdEither & EntityMatchingPatch;
+
+export interface EntityMatchingPatch {
+  update: {
+    /**
+     * Set a new value for the model name.
+     */
+    name?: SinglePatchString;
+    /**
+     * Set a new value for the model description.
+     */
+    description: SinglePatchString;
+  };
+}
+
+export type EntityMatchingPredictRequest = IdEither &
+  EntityMatchingPredictRequestBase;
+
+interface EntityMatchingPredictRequestBase {
+  /**
+   * List of source entities to predict matches for, for example, time series. If omitted, will use data source fit.
+   */
+  sources?: ExternalEntityToMatch[];
+  /**
+   * LList of potential target entities to match to one or more of the source entities, for example, assets. If omitted, will use data from fit.
+   */
+  targets?: ExternalEntityToMatch[];
+  /**
+   * The maximum number of results to return for each matchFrom.
+   */
+  numMatches?: number;
+  /**
+   * Only return matches with score above this threshold.
+   */
+  scoreThreshold?: number;
+}
+
+export interface EntityMatchingPredictResponse
+  extends EntityMatchingResponseBase {
+  /**
+   * Contextualization job ID.
+   */
+  jobId: number;
+}
+
+export type EntityMatchingRefitRequest = IdEither &
+  EntityMatchingRefitRequestBase;
+
+interface EntityMatchingRefitRequestBase {
+  /**
+   * External ID for the new refitted model provided by client. Should be unique within the project.
+   */
+  newExternalId?: CogniteExternalId;
+  /**
+   * List of additional confirmed matches used to train the model. The new model uses a combination of this and trueMatches from the orginal model. If there are identical match-from ids, the pair from the original model is dropped.
+   */
+  trueMatches: ExternalEntityTrueMatch[];
+  /**
+   * List of source entities, for example, time series. If omitted, will use data from fit.
+   */
+  sources?: ExternalEntityToMatch[];
+  /**
+   * List of target entities, for example, assets. If omitted, will use data from fit.
+   */
+  targets?: ExternalEntityToMatch[];
+}
+
+export interface EntityMatchingRefitResponse
+  extends EntityMatchingResponseBase {
+  id: CogniteInternalId;
+  externalId: CogniteExternalId;
+  /**
+   * Defines the combination of features used in the entity matcher model.
+   */
+  featureType: EntityMatchingFeatureType;
+  /**
+   * Name of the classifier used in the model, "Unsupervised" if unsupervised model.
+   */
+  classifier: EntityMatchingClassifier;
+  /**
+   * If True, missing fields in sources or targets entities set in matchFields, are replaced with empty strings.
+   */
+  ignoreMissingFields?: boolean;
+  /**
+   * List of pairs of fields from the target and source items used to calculate features. All source and target items should have all the source and target fields specified here.
+   */
+  matchFields?: EntityMatchingField[];
+  /**
+   * The ID of original model, only relevant when the model is a retrained model.
+   */
+  originalId: CogniteInternalId;
+}
+
+export interface EntityMatchingPredictions {
+  jobId: ContextJobId;
+  /**
+   * The status of the job.
+   */
+  status: ContextJobStatus;
+  /**
+   * List of matched entities with confidence score.
+   */
+  items: EntityMatchingPrediction[];
+}
+
+export interface EntityMatchingPrediction {
+  /**
+   * The matchFrom item given to predict.
+   */
+  matchFrom: ExternalEntityToMatch;
+  /**
+   * Matched items, sorted from highest score to lowest. May be empty.
+   */
+  matches: EntityMatchingPredictedItem[];
+}
+
+export interface EntityMatchingPredictedItem {
+  /**
+   * The matchTo item given to predict.
+   */
+  matchTo: ExternalEntityToMatch;
+  /**
+   * The model's confidence in the match.
+   */
+  score: number;
+}
+
+export interface EntityMatchingFilter {
+  /**
+   * User defined name of the model.
+   */
+  name?: string;
+  /**
+   * User defined description of the model.
+   */
+  description?: string;
+  /**
+   * The feature type used to fit the model.
+   */
+  featureType?: EntityMatchingFeatureType;
+  /**
+   * Name of the classifier supervised model, "Unsupervised" if unsupervised model
+   */
+  classifier?: string;
+  /**
+   * List of pairs of fields from the matchTo and matchFrom items used to create features.
+   */
+  matchFields?: EntityMatchingField[];
+  /**
+   * The ID of original model, only relevant when the model is a retrained model.
+   */
+  originalModelId?: CogniteInternalId;
+}
+
+export interface EntityMatchingFilterRequest extends FilterQuery {
+  filter?: EntityMatchingFilter;
+}

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

113561

increased by89.15%

Number of package files

24

increased by14.29%

Lines of code

2112

increased by142.48%

No dependency changes