Add nearest neighbors support

.changeset/rotten-scissors-wonder.md

@@ -0,0 +1,9 @@
+---
+"@osdk/foundry-sdk-generator": patch
+"@osdk/generator-converters": patch
+"@osdk/shared.test": patch
+"@osdk/client": patch
+"@osdk/api": patch
+---
+
+Add nearest neighbors search support

etc/api.report.api.md

@@ -230,8 +230,9 @@ export interface AsyncIterArgs<
 	R extends boolean = false,
 	A extends Augments = never,
 	S extends NullabilityAdherence = NullabilityAdherence.Default,
-	T extends boolean = false
-> extends SelectArg<Q, K, R, S>, OrderByArg<Q, PropertyKeys<Q>> {
+	T extends boolean = false,
+	Z extends OrderByOptions<Q, K> = {}
+> extends SelectArg<Q, K, R, S>, OrderByArg<Q, Z, PropertyKeys<Q>> {
     	// (undocumented)
     $__UNSTABLE_useOldInterfaceApis?: boolean;
     	// (undocumented)
@@ -273,7 +274,7 @@ export interface BaseObjectSet<Q extends ObjectOrInterfaceDefinition> {
 }
 
 // @public (undocumented)
-export type BaseWirePropertyTypes = "string" | "datetime" | "double" | "boolean" | "integer" | "timestamp" | "short" | "long" | "float" | "decimal" | "byte" | "marking" | "mediaReference" | "numericTimeseries" | "stringTimeseries" | "sensorTimeseries" | "attachment" | "geopoint" | "geoshape" | "geotimeSeriesReference";
+export type BaseWirePropertyTypes = "string" | "datetime" | "double" | "boolean" | "integer" | "timestamp" | "short" | "long" | "float" | "decimal" | "byte" | "marking" | "mediaReference" | "numericTimeseries" | "stringTimeseries" | "sensorTimeseries" | "attachment" | "geopoint" | "geoshape" | "geotimeSeriesReference" | "vector";
 
 // @public (undocumented)
 export type CompileTimeMetadata<T extends {
@@ -504,8 +505,9 @@ export interface FetchPageArgs<
 	R extends boolean = false,
 	A extends Augments = never,
 	S extends NullabilityAdherence = NullabilityAdherence.Default,
-	T extends boolean = false
-> extends AsyncIterArgs<Q, K, R, A, S, T> {
+	T extends boolean = false,
+	Z extends OrderByOptions<Q, K> = {}
+> extends AsyncIterArgs<Q, K, R, A, S, T, Z> {
     	// (undocumented)
     $nextPageToken?: string;
     	// (undocumented)
@@ -520,8 +522,9 @@ export type FetchPageResult<
 	L extends PropertyKeys<Q>,
 	R extends boolean,
 	S extends NullabilityAdherence,
-	T extends boolean
-> = PageResult<PropertyKeys<Q> extends L ? Osdk.Instance<Q, ExtractOptions<R, S, T>> : Osdk.Instance<Q, ExtractOptions<R, S, T>, L>>;
+	T extends boolean,
+	Z extends OrderByOptions<Q, L> = {}
+> = PageResult<Z extends "relevance" ? WithOrderByRelevance<Osdk.Instance<Q, ExtractOptions<R, S, T>, PropertyKeys<Q> extends L ? never : L>> : Osdk.Instance<Q, ExtractOptions<R, S, T>, PropertyKeys<Q> extends L ? never : L>>;
 
 // @public (undocumented)
 export type FilteredPropertyKeys<
@@ -837,6 +840,12 @@ export interface OntologyMetadata<_NEVER_USED_KEPT_FOR_BACKCOMPAT = any> {
     userAgent: string;
 }
 
+// @public (undocumented)
+export type OrderByOptions<
+	Q extends ObjectOrInterfaceDefinition,
+	L extends PropertyKeys<Q> = PropertyKeys<Q>
+> = { [K in L]? : "asc" | "desc" } | "relevance";
+
 // Warning: (ae-forgotten-export) The symbol "IsNever" needs to be exported by the entry point index.d.ts
 // Warning: (ae-forgotten-export) The symbol "IsAny" needs to be exported by the entry point index.d.ts
 // Warning: (ae-forgotten-export) The symbol "ExtractPropsKeysFromOldPropsStyle" needs to be exported by the entry point index.d.ts
@@ -989,6 +998,8 @@ export interface PropertyValueWireToClient {
     stringTimeseries: TimeSeriesProperty<string>;
     	// (undocumented)
     timestamp: string;
+    	// (undocumented)
+    vector: number[];
 }
 
 // Warning: (ae-forgotten-export) The symbol "PrimitiveDataType" needs to be exported by the entry point index.d.ts
@@ -1147,8 +1158,9 @@ export type SingleOsdkResult<
 	R extends boolean,
 	S extends NullabilityAdherence,
 	RDPs extends Record<string, SimplePropertyDef> = {},
-	T extends boolean = false
-> = Osdk.Instance<Q, ExtractOptions<R, S, T>, PropertyKeys<Q> extends L ? PropertyKeys<Q> : PropertyKeys<Q> & L, { [K in Extract<keyof RDPs, L>] : RDPs[K] }>;
+	T extends boolean = false,
+	Z extends OrderByOptions<Q, L> = {}
+> = Z extends "relevance" ? WithOrderByRelevance<Osdk.Instance<Q, ExtractOptions<R, S, T>, PropertyKeys<Q> extends L ? PropertyKeys<Q> : PropertyKeys<Q> & L, { [K in Extract<keyof RDPs, L>] : RDPs[K] }>> : Osdk.Instance<Q, ExtractOptions<R, S, T>, PropertyKeys<Q> extends L ? PropertyKeys<Q> : PropertyKeys<Q> & L, { [K in Extract<keyof RDPs, L>] : RDPs[K] }>;
 
 // Warning: (ae-forgotten-export) The symbol "AllowedBucketKeyTypes_2" needs to be exported by the entry point index.d.ts
 //
@@ -1287,6 +1299,11 @@ export type WhereClause<T extends ObjectOrInterfaceDefinition> = OrWhereClause<T
 // @public (undocumented)
 export type WirePropertyTypes = BaseWirePropertyTypes | Record<string, BaseWirePropertyTypes>;
 
+// @public (undocumented)
+export type WithOrderByRelevance<T extends Osdk.Instance<any>> = T & {
+    	$score: number
+};
+
 // Warnings were encountered during analysis:
 //
 // src/aggregate/AggregateOpts.ts:25:3 - (ae-forgotten-export) The symbol "UnorderedAggregationClause" needs to be exported by the entry point index.d.ts

packages/api/src/OsdkObjectFrom.test.ts

@@ -18,7 +18,11 @@ import { describe, expectTypeOf, it } from "vitest";
 import type { NullabilityAdherence } from "./object/FetchPageArgs.js";
 import type { ObjectSet } from "./objectSet/ObjectSet.js";
 import type { ObjectOrInterfaceDefinition } from "./ontology/ObjectOrInterface.js";
-import type { ExtractOptions, Osdk } from "./OsdkObjectFrom.js";
+import type {
+  ExtractOptions,
+  Osdk,
+  WithOrderByRelevance,
+} from "./OsdkObjectFrom.js";
 
 describe("ExtractOptions", () => {
   describe("NullabilityAdherence Generic", () => {
@@ -359,7 +363,10 @@ describe("ExtractOptions", () => {
     it("is not $notStrict", async () => {
       expectTypeOf<ReturnType<Helper<quickAndDirty>["go"]>>().branded
         .toEqualTypeOf<
-          Osdk.Instance<quickAndDirty>[]
+          (
+            | WithOrderByRelevance<Osdk.Instance<quickAndDirty>>
+            | Osdk.Instance<quickAndDirty>
+          )[]
         >();
     });
   });

packages/api/src/OsdkObjectFrom.ts

@@ -190,6 +190,10 @@ export type Osdk<
       ExtractPropsKeysFromOldPropsStyle<Q, OPTIONS>
     >;
 
+export type WithOrderByRelevance<T extends Osdk.Instance<any>> = T & {
+  $score: number;
+};
+
 export namespace Osdk {
   export type Instance<
     Q extends ObjectOrInterfaceDefinition,

packages/api/src/index.ts

@@ -65,6 +65,7 @@ export type {
   Augments,
   FetchPageArgs,
   NullabilityAdherence,
+  OrderByOptions,
   SelectArg,
   SelectArgToKeys,
 } from "./object/FetchPageArgs.js";
@@ -117,7 +118,11 @@ export type {
 } from "./ontology/WirePropertyTypes.js";
 export type { OsdkBase, PrimaryKeyType } from "./OsdkBase.js";
 export type { OsdkObject } from "./OsdkObject.js";
-export type { ConvertProps, Osdk } from "./OsdkObjectFrom.js";
+export type {
+  ConvertProps,
+  Osdk,
+  WithOrderByRelevance,
+} from "./OsdkObjectFrom.js";
 export type { PageResult } from "./PageResult.js";
 export type {
   Range,

packages/api/src/mapping/PropertyValueMapping.ts

@@ -45,6 +45,7 @@ export interface PropertyValueWireToClient {
   stringTimeseries: TimeSeriesProperty<string>;
   sensorTimeseries: TimeSeriesProperty<string | number>;
   geotimeSeriesReference: GeotimeSeriesProperty<GeoJSON.Point>;
+  vector: number[];
 }
 
 export type GetClientPropertyValueFromWire<
@@ -80,6 +81,7 @@ export interface PropertyValueClientToWire {
   stringTimeseries: TimeSeriesProperty<string>;
   sensorTimeseries: TimeSeriesProperty<string | number>;
   geotimeSeriesReference: GeotimeSeriesProperty<GeoJSON.Point>;
+  vector: number[];
 }
 export type GetWirePropertyValueFromClient<
   T extends

packages/api/src/object/FetchPageArgs.ts

@@ -35,13 +35,21 @@ export interface SelectArg<
   $includeRid?: R;
 }
 
+export type OrderByOptions<
+  Q extends ObjectOrInterfaceDefinition,
+  L extends PropertyKeys<Q> = PropertyKeys<Q>,
+> =
+  | {
+    [K in L]?: "asc" | "desc";
+  }
+  | "relevance";
+
 export interface OrderByArg<
   Q extends ObjectOrInterfaceDefinition,
+  Z extends OrderByOptions<Q, L>,
   L extends PropertyKeys<Q> = PropertyKeys<Q>,
 > {
-  $orderBy?: {
-    [K in L]?: "asc" | "desc";
-  };
+  $orderBy?: Z;
 }
 
 export type SelectArgToKeys<
@@ -58,7 +66,8 @@ export interface FetchPageArgs<
   A extends Augments = never,
   S extends NullabilityAdherence = NullabilityAdherence.Default,
   T extends boolean = false,
-> extends AsyncIterArgs<Q, K, R, A, S, T> {
+  Z extends OrderByOptions<Q, K> = {},
+> extends AsyncIterArgs<Q, K, R, A, S, T, Z> {
   $nextPageToken?: string;
   $pageSize?: number;
 }
@@ -70,7 +79,8 @@ export interface AsyncIterArgs<
   A extends Augments = never,
   S extends NullabilityAdherence = NullabilityAdherence.Default,
   T extends boolean = false,
-> extends SelectArg<Q, K, R, S>, OrderByArg<Q, PropertyKeys<Q>> {
+  Z extends OrderByOptions<Q, K> = {},
+> extends SelectArg<Q, K, R, S>, OrderByArg<Q, Z, PropertyKeys<Q>> {
   $__UNSTABLE_useOldInterfaceApis?: boolean;
   $includeAllBaseObjectProperties?: T;
 }

packages/api/src/object/FetchPageResult.ts

@@ -19,9 +19,14 @@ import type {
   PropertyKeys,
 } from "../ontology/ObjectOrInterface.js";
 import type { SimplePropertyDef } from "../ontology/SimplePropertyDef.js";
-import type { ExtractOptions, IsNever, Osdk } from "../OsdkObjectFrom.js";
+import type {
+  ExtractOptions,
+  IsNever,
+  Osdk,
+  WithOrderByRelevance,
+} from "../OsdkObjectFrom.js";
 import type { PageResult } from "../PageResult.js";
-import type { NullabilityAdherence } from "./FetchPageArgs.js";
+import type { NullabilityAdherence, OrderByOptions } from "./FetchPageArgs.js";
 
 /** exposed for a test */
 export type RespectNullability<S extends NullabilityAdherence> = S extends false
@@ -52,9 +57,20 @@ export type FetchPageResult<
   R extends boolean,
   S extends NullabilityAdherence,
   T extends boolean,
+  Z extends OrderByOptions<Q, L> = {},
 > = PageResult<
-  PropertyKeys<Q> extends L ? Osdk.Instance<Q, ExtractOptions<R, S, T>>
-    : Osdk.Instance<Q, ExtractOptions<R, S, T>, L>
+  Z extends "relevance" ? WithOrderByRelevance<
+      Osdk.Instance<
+        Q,
+        ExtractOptions<R, S, T>,
+        PropertyKeys<Q> extends L ? never : L
+      >
+    >
+    : Osdk.Instance<
+      Q,
+      ExtractOptions<R, S, T>,
+      PropertyKeys<Q> extends L ? never : L
+    >
 >;
 
 /**
@@ -67,12 +83,21 @@ export type SingleOsdkResult<
   S extends NullabilityAdherence,
   RDPs extends Record<string, SimplePropertyDef> = {},
   T extends boolean = false,
-> = Osdk.Instance<
-  Q,
-  ExtractOptions<R, S, T>,
-  PropertyKeys<Q> extends L ? PropertyKeys<Q> : PropertyKeys<Q> & L,
-  { [K in Extract<keyof RDPs, L>]: RDPs[K] }
->;
+  Z extends OrderByOptions<Q, L> = {},
+> = Z extends "relevance" ? WithOrderByRelevance<
+    Osdk.Instance<
+      Q,
+      ExtractOptions<R, S, T>,
+      PropertyKeys<Q> extends L ? PropertyKeys<Q> : PropertyKeys<Q> & L,
+      { [K in Extract<keyof RDPs, L>]: RDPs[K] }
+    >
+  >
+  : Osdk.Instance<
+    Q,
+    ExtractOptions<R, S, T>,
+    PropertyKeys<Q> extends L ? PropertyKeys<Q> : PropertyKeys<Q> & L,
+    { [K in Extract<keyof RDPs, L>]: RDPs[K] }
+  >;
 
 export type IsAny<T> = unknown extends T
   ? [keyof T] extends [never] ? false : true