SearchClient.GetDocumentAsync Method
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Overloads
| Name | Description |
|---|---|
| GetDocumentAsync(String, String, Nullable<Boolean>, IEnumerable<String>, RequestContext) |
[Protocol Method] Retrieves a document from the index.
|
| GetDocumentAsync<T>(String, GetDocumentOptions, CancellationToken) |
Retrieves a document from Azure AI Search. This is useful when a user clicks on a specific search result, and you want to look up specific details about that document. You can only get one document at a time. Use Search to get multiple documents in a single request. Lookup Document |
| GetDocumentAsync<T>(String, String, Nullable<Boolean>, GetDocumentOptions, CancellationToken) |
Retrieves a specific document from the search index, with support
for document-level security via |
GetDocumentAsync(String, String, Nullable<Boolean>, IEnumerable<String>, RequestContext)
- Source:
- SearchClient.cs
[Protocol Method] Retrieves a document from the index.
- This protocol method allows explicit creation of the request and processing of the response for advanced scenarios.
public virtual System.Threading.Tasks.Task<Azure.Response> GetDocumentAsync(string key, string querySourceAuthorization = default, bool? enableElevatedRead = default, System.Collections.Generic.IEnumerable<string> selectedFields = default, Azure.RequestContext context = default);abstract member GetDocumentAsync : string * string * Nullable<bool> * seq<string> * Azure.RequestContext -> System.Threading.Tasks.Task<Azure.Response>
override this.GetDocumentAsync : string * string * Nullable<bool> * seq<string> * Azure.RequestContext -> System.Threading.Tasks.Task<Azure.Response>Public Overridable Function GetDocumentAsync (key As String, Optional querySourceAuthorization As String = Nothing, Optional enableElevatedRead As Nullable(Of Boolean) = Nothing, Optional selectedFields As IEnumerable(Of String) = Nothing, Optional context As RequestContext = Nothing) As Task(Of Response)Parameters
- key
- String
The key of the document to retrieve.
- querySourceAuthorization
- String
Token identifying the user for which the query is being executed. This token is used to enforce security restrictions on documents.
A value that enables elevated read that bypass document level permission checks for the query operation.
- selectedFields
- IEnumerable<String>
List of field names to retrieve for the document; Any field not retrieved will be missing from the returned document.
- context
- RequestContext
The request options, which can override default behaviors of the client pipeline on a per-call basis.
Returns
The response returned from the service.
Exceptions
key is null.
key is an empty string, and was expected to be non-empty.
Service returned a non-success status code.
Applies to
GetDocumentAsync<T>(String, GetDocumentOptions, CancellationToken)
- Source:
- SearchClient.cs
- Source:
- SearchClient.cs
Retrieves a document from Azure AI Search. This is useful when a user clicks on a specific search result, and you want to look up specific details about that document. You can only get one document at a time. Use Search to get multiple documents in a single request. Lookup Document
public virtual System.Threading.Tasks.Task<Azure.Response<T>> GetDocumentAsync<T>(string key, Azure.Search.Documents.GetDocumentOptions options = default, System.Threading.CancellationToken cancellationToken = default);abstract member GetDocumentAsync : string * Azure.Search.Documents.GetDocumentOptions * System.Threading.CancellationToken -> System.Threading.Tasks.Task<Azure.Response<'T>>
override this.GetDocumentAsync : string * Azure.Search.Documents.GetDocumentOptions * System.Threading.CancellationToken -> System.Threading.Tasks.Task<Azure.Response<'T>>Public Overridable Function GetDocumentAsync(Of T) (key As String, Optional options As GetDocumentOptions = Nothing, Optional cancellationToken As CancellationToken = Nothing) As Task(Of Response(Of T))Type Parameters
- T
The .NET type that maps to the index schema. Instances of this type can be retrieved as documents from the index.
Parameters
- key
- String
Required. An string value that uniquely identifies each document in the index. The key is sometimes referred to as a document ID. See Naming rules for the rules for constructing valid document keys.
- options
- GetDocumentOptions
Options to customize the operation's behavior.
- cancellationToken
- CancellationToken
Optional CancellationToken to propagate notifications that the operation should be canceled.
Returns
The document corresponding to the key.
Exceptions
Thrown when a failure is returned by the Search Service.
Remarks
The GetDocument<T>(String, GetDocumentOptions, CancellationToken) and GetDocumentAsync<T>(String, GetDocumentOptions, CancellationToken) methods support mapping of Azure Search field types to .NET types via the type parameter T. Note that all search field types except collections are nullable, so we recommend using nullable types for the properties of T. The type mapping is as follows:
| Search field type | .NET type | ||||||
|---|---|---|---|---|---|---|---|
| Edm.String | String (string in C# and F#) | ||||||
| Edm.Boolean | Nullable<T> (bool? in C#,\ Nullable<bool> in F#) | ||||||
| Edm.Double | Nullable<T> (double? in C#, Nullable<float> in F#) | ||||||
| Edm.Int32 | Nullable<T> (int? in C#, Nullable<int> in F#) | ||||||
| Edm.Int64 | Nullable<T> (long? in C#, Nullable<int64> in F#) | ||||||
| Edm.DateTimeOffset | Nullable<T> (DateTimeOffset? in C#, Nullable<DateTimeOffset> in F#) or System.Nullable<System.DateTime> (DateTime? in C#, Nullable<DateTime> in F#). Both types work, although we recommend using DateTimeOffset. When retrieving documents, DateTime values will always be in UTC. When indexing documents, DateTime values are interpreted as follows:
| ||||||
| Edm.GeographyPoint | Azure.Core.GeoJson.GeoPoint | ||||||
| Edm.ComplexType | Any type that can be deserialized from the JSON objects in the complex field. This can be a value type or a reference type, but we recommend using a reference type since complex fields are nullable in Azure AI Search. | ||||||
| Collection(Edm.String) | IEnumerable<T> (seq<string> in F#) | ||||||
| Collection(Edm.Boolean) | IEnumerable<T> (seq<bool> in F#) | ||||||
| Collection(Edm.Double) | IEnumerable<T> (seq<float> in F#) | ||||||
| Collection(Edm.Int32) | IEnumerable<T> (seq<int> in F#) | ||||||
| Collection(Edm.Int64) | IEnumerable<T> (seq<int64> in F#) | ||||||
| Collection(Edm.DateTimeOffset) | IEnumerable<T> or IEnumerable<T> (seq<DateTimeOffset> or seq<DateTime> in F#). Both types work, although we recommend using IEnumerable<T>. See the notes above on Edm.DateTimeOffset for details. | ||||||
| Collection(Edm.GeographyPoint) | sequence of Azure.Core.GeoJson.GeoPoint (seq<GeoPoint> in F#) | ||||||
| Collection(Edm.ComplexType) | IEnumerable<T> (seq<T> in F#) where T is any type that can be deserialized from the JSON objects in the complex collection field. This can be a value type or a reference type. |
T and we will attempt to map JSON types in the response payload to .NET types. This mapping does not have the benefit of precise type information from the index, so the mapping is not always correct. In particular, be aware of the following cases: - Any numeric value without a decimal point will be deserialized to a Int32 (int in C#, int32 in F#) if it can be converted or a Int64 (long in C#, int64 in F#) otherwise.
- Special double-precision floating point values such as NaN and Infinity will be deserialized as type String rather than Double, even if they are in arrays with regular floating point values.
- Any Edm.DateTimeOffset field will be deserialized as a DateTimeOffset, not DateTime.
- Any empty JSON array will be deserialized as an array of Object (object[] in C#, obj[] in F#).
- Complex fields will be recursively deserialized into instances of type SearchDocument. Similarly, complex collection fields will be deserialized into arrays of such instances.
Applies to
GetDocumentAsync<T>(String, String, Nullable<Boolean>, GetDocumentOptions, CancellationToken)
- Source:
- SearchClient.cs
Retrieves a specific document from the search index, with support
for document-level security via querySourceAuthorization.
Lookup Document
public virtual System.Threading.Tasks.Task<Azure.Response<T>> GetDocumentAsync<T>(string key, string querySourceAuthorization, bool? enableElevatedRead = default, Azure.Search.Documents.GetDocumentOptions options = default, System.Threading.CancellationToken cancellationToken = default);abstract member GetDocumentAsync : string * string * Nullable<bool> * Azure.Search.Documents.GetDocumentOptions * System.Threading.CancellationToken -> System.Threading.Tasks.Task<Azure.Response<'T>>
override this.GetDocumentAsync : string * string * Nullable<bool> * Azure.Search.Documents.GetDocumentOptions * System.Threading.CancellationToken -> System.Threading.Tasks.Task<Azure.Response<'T>>Public Overridable Function GetDocumentAsync(Of T) (key As String, querySourceAuthorization As String, Optional enableElevatedRead As Nullable(Of Boolean) = Nothing, Optional options As GetDocumentOptions = Nothing, Optional cancellationToken As CancellationToken = Nothing) As Task(Of Response(Of T))Type Parameters
- T
The .NET type that maps to the index schema. Instances of this type can be retrieved as documents from the index.
Parameters
- key
- String
The key of the document to retrieve.
- querySourceAuthorization
- String
Token identifying the user for whom the query is being executed. This token is used to enforce document-level security restrictions.
A value that enables elevated read access that bypasses document-level permission checks for the query operation.
- options
- GetDocumentOptions
Options to customize the operation's behavior.
- cancellationToken
- CancellationToken
Optional CancellationToken to propagate notifications that the operation should be canceled.
Returns
The document corresponding to the key as a
T.
Exceptions
Thrown when a failure is returned by the Search Service.
Remarks
The GetDocument<T>(String, String, Nullable<Boolean>, GetDocumentOptions, CancellationToken) and GetDocumentAsync<T>(String, String, Nullable<Boolean>, GetDocumentOptions, CancellationToken) methods support mapping of Azure Search field types to .NET types via the type parameter T. Note that all search field types except collections are nullable, so we recommend using nullable types for the properties of T. The type mapping is as follows:
| Search field type | .NET type | ||||||
|---|---|---|---|---|---|---|---|
| Edm.String | String (string in C# and F#) | ||||||
| Edm.Boolean | Nullable<T> (bool? in C#,\ Nullable<bool> in F#) | ||||||
| Edm.Double | Nullable<T> (double? in C#, Nullable<float> in F#) | ||||||
| Edm.Int32 | Nullable<T> (int? in C#, Nullable<int> in F#) | ||||||
| Edm.Int64 | Nullable<T> (long? in C#, Nullable<int64> in F#) | ||||||
| Edm.DateTimeOffset | Nullable<T> (DateTimeOffset? in C#, Nullable<DateTimeOffset> in F#) or System.Nullable<System.DateTime> (DateTime? in C#, Nullable<DateTime> in F#). Both types work, although we recommend using DateTimeOffset. When retrieving documents, DateTime values will always be in UTC. When indexing documents, DateTime values are interpreted as follows:
| ||||||
| Edm.GeographyPoint | Azure.Core.GeoJson.GeoPoint | ||||||
| Edm.ComplexType | Any type that can be deserialized from the JSON objects in the complex field. This can be a value type or a reference type, but we recommend using a reference type since complex fields are nullable in Azure AI Search. | ||||||
| Collection(Edm.String) | IEnumerable<T> (seq<string> in F#) | ||||||
| Collection(Edm.Boolean) | IEnumerable<T> (seq<bool> in F#) | ||||||
| Collection(Edm.Double) | IEnumerable<T> (seq<float> in F#) | ||||||
| Collection(Edm.Int32) | IEnumerable<T> (seq<int> in F#) | ||||||
| Collection(Edm.Int64) | IEnumerable<T> (seq<int64> in F#) | ||||||
| Collection(Edm.DateTimeOffset) | IEnumerable<T> or IEnumerable<T> (seq<DateTimeOffset> or seq<DateTime> in F#). Both types work, although we recommend using IEnumerable<T>. See the notes above on Edm.DateTimeOffset for details. | ||||||
| Collection(Edm.GeographyPoint) | sequence of Azure.Core.GeoJson.GeoPoint (seq<GeoPoint> in F#) | ||||||
| Collection(Edm.ComplexType) | IEnumerable<T> (seq<T> in F#) where T is any type that can be deserialized from the JSON objects in the complex collection field. This can be a value type or a reference type. |
T and we will attempt to map JSON types in the response payload to .NET types. This mapping does not have the benefit of precise type information from the index, so the mapping is not always correct. In particular, be aware of the following cases: - Any numeric value without a decimal point will be deserialized to a Int32 (int in C#, int32 in F#) if it can be converted or a Int64 (long in C#, int64 in F#) otherwise.
- Special double-precision floating point values such as NaN and Infinity will be deserialized as type String rather than Double, even if they are in arrays with regular floating point values.
- Any Edm.DateTimeOffset field will be deserialized as a DateTimeOffset, not DateTime.
- Any empty JSON array will be deserialized as an array of Object (object[] in C#, obj[] in F#).
- Complex fields will be recursively deserialized into instances of type SearchDocument. Similarly, complex collection fields will be deserialized into arrays of such instances.
