Skip to content

Commit 4aab6b5

Browse files
deyaaeldeenCopilot
deyaaeldeen
and
Copilot
authored
feat(search-documents): implement Beta Activation pattern for preview surface isolation
Adds enableBeta() method to SearchIndexClient that provides type-safe access to preview API operations. Preview types are exported from a ./beta subpath to keep them invisible to stable consumers. - enableBeta() upgrades API version and returns wider-typed client - SearchIndexClientWithBeta type uses Omit + intersection for clean types - Covers new operations (knowledge bases, aliases), wider return types (BetaSearchIndex), and serialization round-trips - Sidesteps TS assertion narrowing limitation (microsoft/TypeScript#63250) by using return type instead of asserts Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent 14835f8 commit 4aab6b5

16 files changed

Lines changed: 764 additions & 405 deletions

‎sdk/search/search-documents/package.json‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -127,6 +127,24 @@
127127
"default": "./dist/commonjs/index.js"
128128
}
129129
},
130+
"./beta": {
131+
"browser": {
132+
"types": "./dist/browser/beta/index.d.ts",
133+
"default": "./dist/browser/beta/index.js"
134+
},
135+
"react-native": {
136+
"types": "./dist/react-native/beta/index.d.ts",
137+
"default": "./dist/react-native/beta/index.js"
138+
},
139+
"import": {
140+
"types": "./dist/esm/beta/index.d.ts",
141+
"default": "./dist/esm/beta/index.js"
142+
},
143+
"require": {
144+
"types": "./dist/commonjs/beta/index.d.ts",
145+
"default": "./dist/commonjs/beta/index.js"
146+
}
147+
},
130148
"./search": {
131149
"browser": {
132150
"types": "./dist/browser/search/index.d.ts",

‎sdk/search/search-documents/review/search-documents-beta-node.api.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
## API Report File for "@azure/search-documents"
2+
3+
> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
4+
5+
```ts
6+
7+
import type { ClientOptions } from '@azure-rest/core-client';
8+
import type { KeyCredential } from '@azure/core-auth';
9+
import type { OperationOptions } from '@azure-rest/core-client';
10+
import { Pipeline } from '@azure/core-rest-pipeline';
11+
import type { TokenCredential } from '@azure/core-auth';
12+
13+
// @public
14+
export type BetaIndexIterator = PagedAsyncIterableIterator<BetaSearchIndex>;
15+
16+
// @public
17+
export interface BetaSearchIndex extends SearchIndex {
18+
permissionFilterOption?: SearchIndexPermissionFilterOption;
19+
purviewEnabled?: boolean;
20+
}
21+
22+
// @public
23+
export interface SearchIndexClientBetaOperations {
24+
createAlias(alias: SearchIndexAlias, options?: CreateAliasOptions): Promise<SearchIndexAlias>;
25+
createIndex(index: SearchIndex, options?: CreateIndexOptions): Promise<BetaSearchIndex>;
26+
createKnowledgeBase(knowledgeBase: KnowledgeBase, options?: CreateKnowledgeBaseOptions): Promise<KnowledgeBase>;
27+
createKnowledgeSource(knowledgeSource: KnowledgeSource, options?: CreateKnowledgeSourceOptions): Promise<KnowledgeSource>;
28+
createOrUpdateAlias(alias: SearchIndexAlias, options?: CreateOrUpdateAliasOptions): Promise<SearchIndexAlias>;
29+
createOrUpdateIndex(index: SearchIndex, options?: CreateOrUpdateIndexOptions): Promise<BetaSearchIndex>;
30+
createOrUpdateKnowledgeBase(knowledgeBaseName: string, knowledgeBase: KnowledgeBase, options?: CreateOrUpdateKnowledgeBaseOptions): Promise<KnowledgeBase>;
31+
createOrUpdateKnowledgeSource(sourceName: string, knowledgeSource: KnowledgeSource, options?: CreateOrUpdateKnowledgeSourceOptions): Promise<KnowledgeSource>;
32+
deleteAlias(aliasName: string, options?: DeleteAliasOptions): Promise<void>;
33+
deleteAlias(alias: SearchIndexAlias, options?: DeleteAliasOptions): Promise<void>;
34+
deleteKnowledgeBase(knowledgeBaseName: string, options?: DeleteKnowledgeBaseOptions): Promise<void>;
35+
deleteKnowledgeBase(knowledgeBase: KnowledgeBase, options?: DeleteKnowledgeBaseOptions): Promise<void>;
36+
deleteKnowledgeSource(sourceName: string, options?: DeleteKnowledgeSourceOptions): Promise<void>;
37+
deleteKnowledgeSource(source: KnowledgeSource, options?: DeleteKnowledgeSourceOptions): Promise<void>;
38+
getAlias(aliasName: string, options?: GetAliasOptions): Promise<SearchIndexAlias>;
39+
getIndex(indexName: string, options?: GetIndexOptions): Promise<BetaSearchIndex>;
40+
getIndexStatsSummary(options?: GetIndexStatsSummaryOptions): IndexStatisticsSummaryIterator;
41+
getKnowledgeBase(knowledgeBaseName: string, options?: GetKnowledgeBaseOptions): Promise<KnowledgeBase>;
42+
getKnowledgeRetrievalClient(knowledgeBaseName: string, options?: KnowledgeRetrievalClientOptions): KnowledgeRetrievalClient;
43+
getKnowledgeSource(sourceName: string, options?: GetKnowledgeSourceOptions): Promise<KnowledgeSource>;
44+
getKnowledgeSourceStatus(sourceName: string, options?: GetKnowledgeSourceStatusOptions): Promise<KnowledgeSourceStatus>;
45+
listAliases(options?: ListAliasesOptions): AliasIterator;
46+
listIndexes(options?: ListIndexesOptions): BetaIndexIterator;
47+
listKnowledgeBases(options?: ListKnowledgeBasesOptions): KnowledgeBaseIterator;
48+
listKnowledgeSources(options?: ListKnowledgeSourcesOptions): KnowledgeSourceIterator;
49+
}
50+
51+
// @public
52+
export type SearchIndexClientWithBeta = Omit<SearchIndexClient, "listIndexes" | "getIndex" | "createIndex" | "createOrUpdateIndex"> & SearchIndexClientBetaOperations;
53+
54+
// (No @packageDocumentation comment for this package)
55+
56+
```

‎sdk/search/search-documents/review/search-documents-node.api.md‎

Lines changed: 2 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -3353,8 +3353,6 @@ export interface SearchIndex {
33533353
fields: SearchField[];
33543354
name: string;
33553355
normalizers?: LexicalNormalizer[];
3356-
permissionFilterOption?: SearchIndexPermissionFilterOption;
3357-
purviewEnabled?: boolean;
33583356
scoringProfiles?: ScoringProfile[];
33593357
semanticSearch?: SemanticSearch;
33603358
similarity?: SimilarityAlgorithm;
@@ -3373,43 +3371,23 @@ export class SearchIndexClient {
33733371
analyzeText(indexName: string, options: AnalyzeTextOptions): Promise<AnalyzeResult>;
33743372
// @deprecated
33753373
readonly apiVersion: string;
3376-
createAlias(alias: SearchIndexAlias, options?: CreateAliasOptions): Promise<SearchIndexAlias>;
33773374
createIndex(index: SearchIndex, options?: CreateIndexOptions): Promise<SearchIndex>;
3378-
createKnowledgeBase(knowledgeBase: KnowledgeBase, options?: CreateKnowledgeBaseOptions): Promise<KnowledgeBase>;
3379-
createKnowledgeSource(knowledgeSource: KnowledgeSource, options?: CreateKnowledgeSourceOptions): Promise<KnowledgeSource>;
3380-
createOrUpdateAlias(alias: SearchIndexAlias, options?: CreateOrUpdateAliasOptions): Promise<SearchIndexAlias>;
33813375
createOrUpdateIndex(index: SearchIndex, options?: CreateOrUpdateIndexOptions): Promise<SearchIndex>;
3382-
createOrUpdateKnowledgeBase(knowledgeBaseName: string, knowledgeBase: KnowledgeBase, options?: CreateOrUpdateKnowledgeBaseOptions): Promise<KnowledgeBase>;
3383-
// (undocumented)
3384-
createOrUpdateKnowledgeSource(sourceName: string, knowledgeSource: KnowledgeSource, options?: CreateOrUpdateKnowledgeSourceOptions): Promise<KnowledgeSource>;
33853376
createOrUpdateSynonymMap(synonymMap: SynonymMap, options?: CreateOrUpdateSynonymMapOptions): Promise<SynonymMap>;
33863377
createSynonymMap(synonymMap: SynonymMap, options?: CreateSynonymMapOptions): Promise<SynonymMap>;
3387-
deleteAlias(aliasName: string, options?: DeleteAliasOptions): Promise<void>;
3388-
deleteAlias(alias: SearchIndexAlias, options?: DeleteAliasOptions): Promise<void>;
33893378
deleteIndex(indexName: string, options?: DeleteIndexOptions): Promise<void>;
33903379
deleteIndex(index: SearchIndex, options?: DeleteIndexOptions): Promise<void>;
3391-
deleteKnowledgeBase(knowledgeBaseName: string, options?: DeleteKnowledgeBaseOptions): Promise<void>;
3392-
deleteKnowledgeBase(knowledgeBase: KnowledgeBase, options?: DeleteKnowledgeBaseOptions): Promise<void>;
3393-
deleteKnowledgeSource(sourceName: string, options?: DeleteKnowledgeSourceOptions): Promise<void>;
3394-
deleteKnowledgeSource(source: KnowledgeSource, options?: DeleteKnowledgeSourceOptions): Promise<void>;
33953380
deleteSynonymMap(synonymMap: string | SynonymMap, options?: DeleteSynonymMapOptions): Promise<void>;
3381+
// Warning: (ae-forgotten-export) The symbol "SearchIndexClientWithBeta" needs to be exported by the entry point index.d.ts
3382+
enableBeta(): SearchIndexClientWithBeta;
33963383
readonly endpoint: string;
3397-
getAlias(aliasName: string, options?: GetAliasOptions): Promise<SearchIndexAlias>;
33983384
getIndex(indexName: string, options?: GetIndexOptions): Promise<SearchIndex>;
33993385
getIndexStatistics(indexName: string, options?: GetIndexStatisticsOptions): Promise<SearchIndexStatistics>;
3400-
getIndexStatsSummary(options?: GetIndexStatsSummaryOptions): IndexStatisticsSummaryIterator;
3401-
getKnowledgeBase(knowledgeBaseName: string, options?: GetKnowledgeBaseOptions): Promise<KnowledgeBase>;
3402-
getKnowledgeRetrievalClient(knowledgeBaseName: string, options?: KnowledgeRetrievalClientOptions): KnowledgeRetrievalClient;
3403-
getKnowledgeSource(sourceName: string, options?: GetKnowledgeSourceOptions): Promise<KnowledgeSource>;
3404-
getKnowledgeSourceStatus(sourceName: string, options?: GetKnowledgeSourceStatusOptions): Promise<KnowledgeSourceStatus>;
34053386
getSearchClient<TModel extends object>(indexName: string, options?: SearchClientOptions): SearchClient<TModel>;
34063387
getServiceStatistics(options?: GetServiceStatisticsOptions): Promise<SearchServiceStatistics>;
34073388
getSynonymMap(synonymMapName: string, options?: GetSynonymMapsOptions): Promise<SynonymMap>;
3408-
listAliases(options?: ListAliasesOptions): AliasIterator;
34093389
listIndexes(options?: ListIndexesOptions): IndexIterator;
34103390
listIndexesNames(options?: ListIndexesOptions): IndexNameIterator;
3411-
listKnowledgeBases(options?: ListKnowledgeBasesOptions): KnowledgeBaseIterator;
3412-
listKnowledgeSources(options?: ListKnowledgeSourcesOptions): KnowledgeSourceIterator;
34133391
listSynonymMaps(options?: ListSynonymMapsOptions): Promise<Array<SynonymMap>>;
34143392
listSynonymMapsNames(options?: ListSynonymMapsOptions): Promise<Array<string>>;
34153393
readonly pipeline: Pipeline;

‎sdk/search/search-documents/samples-dev/betaOperations.ts‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
// Copyright (c) Microsoft Corporation.
2+
// Licensed under the MIT License.
3+
4+
/**
5+
* @summary Demonstrates how to use enableBeta() to access preview operations.
6+
*/
7+
8+
import { DefaultAzureCredential } from "@azure/identity";
9+
import { SearchIndexClient } from "@azure/search-documents";
10+
import "dotenv/config";
11+
12+
const endpoint = process.env.ENDPOINT || "";
13+
14+
async function usePreviewOperations(): Promise<void> {
15+
// Activate preview operations on this client instance.
16+
// enableBeta() returns the same instance with a wider type that includes
17+
// preview-only operations such as alias management, knowledge base
18+
// operations, and index statistics summary.
19+
const client = new SearchIndexClient(endpoint, new DefaultAzureCredential()).enableBeta();
20+
21+
// Preview-only: list all search index aliases
22+
console.log("Listing aliases (preview operation):");
23+
for await (const alias of client.listAliases()) {
24+
console.log(` Alias: ${alias.name} -> [${alias.indexes.join(", ")}]`);
25+
}
26+
27+
// Preview-only: get aggregated index statistics summary
28+
console.log(`\nIndex stats summary (preview operation):`);
29+
for await (const stat of client.getIndexStatsSummary()) {
30+
console.log(` vectorIndexSize: ${stat.vectorIndexSize}`);
31+
}
32+
}
33+
34+
async function main(): Promise<void> {
35+
console.log(`Running Beta Operations Sample....`);
36+
if (!endpoint) {
37+
console.log("Be sure to set a valid endpoint with proper authorization.");
38+
return;
39+
}
40+
await usePreviewOperations();
41+
}
42+
43+
main().catch((err) => {
44+
console.error("The sample encountered an error:", err);
45+
});

‎sdk/search/search-documents/src/beta/index.ts‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
// Copyright (c) Microsoft Corporation.
2+
// Licensed under the MIT License.
3+
4+
export type {
5+
SearchIndexClientBetaOperations,
6+
SearchIndexClientWithBeta,
7+
} from "../searchIndexClient.js";
8+
9+
export type { BetaIndexIterator, BetaSearchIndex } from "../serviceModels.js";

‎sdk/search/search-documents/src/knowledgeRetrievalClient.ts‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ import { createOdataMetadataPolicy } from "./odataMetadataPolicy.js";
2222
import { createSearchApiKeyCredentialPolicy } from "./searchApiKeyCredentialPolicy.js";
2323
import { KnownSearchAudience } from "./searchAudience.js";
2424
import * as utils from "./serviceUtils.js";
25+
import { previewServiceVersion } from "./serviceUtils.js";
2526
import { tracingClient } from "./tracing.js";
2627
import type { ClientOptions } from "@azure-rest/core-client";
2728

@@ -105,7 +106,7 @@ export class KnowledgeRetrievalClient {
105106

106107
const internalClientPipelineOptions: KnowledgeBaseRetrievalClientOptionalParams = {
107108
...options,
108-
apiVersion: options.serviceVersion ?? utils.defaultServiceVersion,
109+
apiVersion: options.serviceVersion ?? previewServiceVersion,
109110
...{
110111
loggingOptions: {
111112
logger: logger.info,
@@ -121,7 +122,7 @@ export class KnowledgeRetrievalClient {
121122
},
122123
};
123124

124-
this.serviceVersion = options.serviceVersion ?? utils.defaultServiceVersion;
125+
this.serviceVersion = options.serviceVersion ?? previewServiceVersion;
125126

126127
this.client = new GeneratedClient(endpoint, credential, internalClientPipelineOptions);
127128

0 commit comments

Comments
 (0)