diff --git a/client/extension-api/src/sourcegraph.d.ts b/client/extension-api/src/sourcegraph.d.ts index e4cac60450c..21f9aa601e4 100644 --- a/client/extension-api/src/sourcegraph.d.ts +++ b/client/extension-api/src/sourcegraph.d.ts @@ -1253,7 +1253,7 @@ declare module 'sourcegraph' { * A search context is a set of repositories and revisions on a Sourcegraph instance. * When set, extensions use it to scope search queries, code intelligence actions, etc. * - * See more information at https://docs.sourcegraph.com/code_search/explanations/features#search-contexts-experimental. + * See more information at https://docs.sourcegraph.com/code_search/explanations/features#search-contexts. */ export const searchContext: string | undefined diff --git a/client/web/src/search/input/SearchContextDropdown.tsx b/client/web/src/search/input/SearchContextDropdown.tsx index 78427169f0f..174e50e3c06 100644 --- a/client/web/src/search/input/SearchContextDropdown.tsx +++ b/client/web/src/search/input/SearchContextDropdown.tsx @@ -61,7 +61,7 @@ function getHighlightTourStep(onClose: () => void): HTMLElement {
Search just the code you care about with search contexts.
- + Learn more
diff --git a/client/web/src/searchContexts/ConvertVersionContextsPage.tsx b/client/web/src/searchContexts/ConvertVersionContextsPage.tsx index c2331639acc..0c3e5260a14 100644 --- a/client/web/src/searchContexts/ConvertVersionContextsPage.tsx +++ b/client/web/src/searchContexts/ConvertVersionContextsPage.tsx @@ -129,7 +129,7 @@ export const ConvertVersionContextsPage: React.FunctionComponent Convert existing version contexts defined in site config into search contexts.{' '} diff --git a/client/web/src/searchContexts/CreateSearchContextPage.tsx b/client/web/src/searchContexts/CreateSearchContextPage.tsx index 49b2c1dc259..74419ae6325 100644 --- a/client/web/src/searchContexts/CreateSearchContextPage.tsx +++ b/client/web/src/searchContexts/CreateSearchContextPage.tsx @@ -52,7 +52,7 @@ export const AuthenticatedCreateSearchContextPage: React.FunctionComponent diff --git a/client/web/src/searchContexts/SearchContextsListPage.tsx b/client/web/src/searchContexts/SearchContextsListPage.tsx index 16d85af1b5b..bc934cb0922 100644 --- a/client/web/src/searchContexts/SearchContextsListPage.tsx +++ b/client/web/src/searchContexts/SearchContextsListPage.tsx @@ -84,7 +84,7 @@ export const SearchContextsListPage: React.FunctionComponent Search code you care about with search contexts.{' '} diff --git a/doc/admin/how-to/converting-version-contexts-to-search-contexts.md b/doc/admin/how-to/converting-version-contexts-to-search-contexts.md index 7b16b74d1a8..b7d839032fd 100644 --- a/doc/admin/how-to/converting-version-contexts-to-search-contexts.md +++ b/doc/admin/how-to/converting-version-contexts-to-search-contexts.md @@ -1,6 +1,6 @@ # How to convert version contexts to search contexts -This guide will provide steps for migrating from [version contexts](../../code_search/explanations/features.md#version-contexts-sunsetting) to [search contexts](../../code_search/explanations/features.md#search-contexts-experimental) on your private Sourcegraph instance. +This guide will provide steps for migrating from [version contexts](../../code_search/explanations/features.md#version-contexts-sunsetting) to [search contexts](../../code_search/explanations/features.md#search-contexts) on your private Sourcegraph instance. ## Prerequisites diff --git a/doc/api/graphql/managing-search-contexts-with-api.md b/doc/api/graphql/managing-search-contexts-with-api.md new file mode 100644 index 00000000000..faca91f82b3 --- /dev/null +++ b/doc/api/graphql/managing-search-contexts-with-api.md @@ -0,0 +1,189 @@ +# Managing search contexts with the API + +Learn how to manage [search contexts](../../code_search/how-to/search_contexts.md) on private Sourcegraph instances with the API. If you haven't used the API before, learn more about [the GraphQL API and how to use it](index.md). + +## Prerequisites + +* Search contexts and search context management are [enabled in global settings](../../code_search/explanations/features.md#search-contexts). + +### Permissions and visibility overview + +To read and write search contexts through the API you will need appropriate permissions. The permissions are determined based on the individual search context's namespace and its visibility (private or public). + +**Read** permissions (view contents, use in searches): + +* **Public** search contexts are available to everyone + * Including unauthenticated users only on Sourcegraph Cloud +* **Private** search contexts + * With user namespace: only available to the user + * With organization namespace: only available to users in the organization + * With global (instance-level) namespace: only available to site-admins + +**Write** permissions (create, update, delete): + +* Site-admins have write access to all public search contexts and all global (instance-level) search contexts +* A regular user has write access to its search contexts and its organization's search contexts + +## Create a context + +Below is a GraphQL query that creates a new search context. To populate the `searchContext.namespace` property, you will have to query the API beforehand to retrieve the user or organization ID. + +If `searchContext.namespace` is not specified or `null` then the context is created in the global (instance-level) namespace. +To specify search context repositories you will need their ids. Similar to the `namespace` property you will need to retrieve them from the API before creating the context. + +```gql +mutation CreateSearchContext( + $searchContext: SearchContextInput! + $repositories: [SearchContextRepositoryRevisionsInput!]! +) { + createSearchContext(searchContext: $searchContext, repositories: $repositories) { + id + spec + } +} +``` + +Example variables: + +```json +{ + "searchContext": { + "name": "MySearchContext", + "description": "A description of my search context", + "namespace": "user-id", + "public": true + }, + "repositories": [ + { + "repositoryID": "repo-id", + "revisions": ["main", "branch-1"] + } + ] +} +``` + +## Read a single context + +Below is a GraphQL query that fetches a single search context by ID. + +```gql +query ReadSearchContext($id: ID!) { + node(id: $id) { + ... on SearchContext { + id + spec + } + } +} +``` + +Example variables: + +```json +{ "id": "search-context-id" } +``` + +## List available contexts + +Below is a GraphQL query that fetches all available search contexts and allows filtering by multiple parameters. The `namespaces` array allows filtering by one or multiple namespace ids (user or organization id). +To include global (instance-level) contexts you can specify `null` as one of the ids. If the `namespaces` array is omitted or empty, then no filtering by namespace is applied and all available contexts are returned. +The `query` parameter allows filtering by search context spec. + +```gql +query ListSearchContexts( + $first: Int! + $after: String + $query: String + $namespaces: [ID] + $orderBy: SearchContextsOrderBy + $descending: Boolean +) { + searchContexts( + first: $first + after: $after + query: $query + namespaces: $namespaces + orderBy: $orderBy + descending: $descending + ) { + nodes { + id + spec + } + pageInfo { + hasNextPage + endCursor + } + totalCount + } +} +``` + +Example variables: + +Query with these variables will return the first 50 search contexts ordered by search context `updatedAt` timestamp ascending. The results will be filtered to include only +global contexts (`null`), `organization1` contexts (`organization1-id`), and `user1` contexts (`user1-id`). + +```json +{ + "first": 50, + "namespaces": [null, "organization1-id", "user1-id"], + "orderBy": "SEARCH_CONTEXT_UPDATED_AT", +} +``` + + +## Update a context + +Below is a GraphQL query that updates an existing search context. You cannot update a search context namespace. +You have to provide the full search context and all repositories with revisions you want to keep on each update. + +```gql +mutation UpdateSearchContext( + $id: ID! + $searchContext: SearchContextEditInput! + $repositories: [SearchContextRepositoryRevisionsInput!]! +) { + updateSearchContext(id: $id, searchContext: $searchContext, repositories: $repositories) { + id + spec + } +} +``` + +Example variables: + +```json +{ + "id": "search-context-id-to-update", + "searchContext": { + "name": "MyUpdatedSearchContext", + "description": "An updated description of my search context", + "public": false + }, + "repositories": [ + { + "repositoryID": "repo-id", + "revisions": ["main", "branch-1", "branch-2"] + } + ] +} +``` + +## Delete a context + +Below is a GraphQL query that deletes a search context by ID. + +```gql +mutation DeleteSearchContext($id: ID!) { + deleteSearchContext(id: $id) { + alwaysNil + } +} +``` + +Example variables: + +```json +{ "id": "search-context-id-to-delete" } +``` diff --git a/doc/code_search/explanations/features.md b/doc/code_search/explanations/features.md index 2abb5e8cc66..943da3c50ec 100644 --- a/doc/code_search/explanations/features.md +++ b/doc/code_search/explanations/features.md @@ -118,7 +118,7 @@ Indexing multiple branches will add additional resource requirements to Sourcegr > NOTE: All revisions specified in version contexts are also indexed. -## Search contexts experimental +## Search contexts Search contexts help you search the code you care about on Sourcegraph. A search context represents a set of repositories at specific revisions on a Sourcegraph instance that will be targeted by search queries by default. diff --git a/doc/code_search/explanations/sourcegraph_cloud.md b/doc/code_search/explanations/sourcegraph_cloud.md index b281674d28c..e022d59d035 100644 --- a/doc/code_search/explanations/sourcegraph_cloud.md +++ b/doc/code_search/explanations/sourcegraph_cloud.md @@ -4,7 +4,7 @@ Note that you can search across a maximum of 50 repositories at once using Sourcegraph Cloud. To search across more than 50 repositories at once or to search your organization's internal code, [run your own Sourcegraph instance](../../../admin/install/index.md). -## Search contexts experimental +## Search contexts >NOTE: This feature is still in active development. diff --git a/doc/code_search/how-to/search_contexts.md b/doc/code_search/how-to/search_contexts.md index 12786d63c50..f4002376955 100644 --- a/doc/code_search/how-to/search_contexts.md +++ b/doc/code_search/how-to/search_contexts.md @@ -22,7 +22,7 @@ You can also search across multiple contexts at once using the `OR` [boolean ope **Note**: Creating search contexts is only supported on private Sourcegraph instances. Sourcegraph Cloud does not yet support custom search contexts. Want early access to custom contexts on Sourcegraph Cloud? [Let us know](mailto:feedback@sourcegraph.com). -When search contexts are [enabled on your private Sourcegraph instance](../explanations/features.md#search-contexts-experimental), you can create your own search contexts. +When search contexts are [enabled on your private Sourcegraph instance](../explanations/features.md#search-contexts), you can create your own search contexts. A search context consists of a name, description, and a set of repositories at one or many revisions. @@ -67,6 +67,10 @@ For example: You will be returned to the list of search contexts. Your new search context will appear in the search contexts selector in the search input, and can be [used immediately](#using-search-contexts). +## Managing search contexts with the API + +Learn how to [manage search contexts with the GraphQL API](../../api/graphql/managing-search-contexts-with-api.md). + ## Search contexts on Sourcegraph Cloud -Please see [searching across repositories you've added to Sourcegraph Cloud with search contexts](./searching_with_search_contexts.md). +Learn how to [search across repositories you've added to Sourcegraph Cloud with search contexts](./searching_with_search_contexts.md). diff --git a/doc/code_search/index.md b/doc/code_search/index.md index 9841d0e1299..44fdb2560fb 100644 --- a/doc/code_search/index.md +++ b/doc/code_search/index.md @@ -48,7 +48,7 @@ Sourcegraph code search helps developers perform these tasks more quickly and ef - Search [commit diffs](explanations/features.md#commit-diff-search) and [commit messages](explanations/features.md#commit-message-search) to see how code has changed. - Narrow your search by repository and file pattern. - Define saved [search scopes](explanations/features.md#search-scopes) for easier searching. - - Use [search contexts](explanations/features.md#search-contexts-experimental) to search across a set of repositories at specific revisions. + - Use [search contexts](explanations/features.md#search-contexts) to search across a set of repositories at specific revisions. - Curate [saved searches](explanations/features.md#saved-searches) for yourself or your org. - Set up notifications for code changes that match a query. - View [language statistics](explanations/features.md#statistics) for search results.