Skip to content

Search README issues #11082

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bryevdv merged 3 commits into from
Apr 27, 2020
Merged

Search README issues #11082

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
25ae0e5
fix for azure.search.documents change
bryevdv Apr 27, 2020
f1de857
indentation, naming
bryevdv Apr 27, 2020
06ed975
SearchIndexClient -> SearchClient
bryevdv Apr 27, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
108 changes: 56 additions & 52 deletions sdk/search/azure-search-documents/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,9 +38,9 @@ pip install azure-search-documents --pre

## Key concepts

Azure Cognitive Search has the concepts of search services and indexes and documents, where a search service contains
one or more indexes that provides persistent storage of searchable data, and data is loaded in the form of JSON documents.
Data can be pushed to an index from an external data source, but if you use an indexer, it's possible to crawl a data
Azure Cognitive Search has the concepts of search services and indexes and documents, where a search service contains
one or more indexes that provides persistent storage of searchable data, and data is loaded in the form of JSON documents.
Data can be pushed to an index from an external data source, but if you use an indexer, it's possible to crawl a data
source to extract and load data into an index.

There are several types of operations that can be executed against the service:
Expand All @@ -53,45 +53,45 @@ There are several types of operations that can be executed against the service:

### Authenticate the client

In order to interact with the Cognitive Search service you'll need to create an instance of the Search Client class.
In order to interact with the Cognitive Search service you'll need to create an instance of the Search Client class.
To make this possible you will need an [api-key of the Cognitive Search service](https://docs.microsoft.com/en-us/azure/search/search-security-api-keys).

The SDK provides two clients.

1. SearchIndexClient for all document operations.
1. SearchClient for all document operations.
2. SearchServiceClient for all CRUD operations on service resources.

### Create a SearchServiceClient

Once you have the values of the Cognitive Search Service [service endpoint](https://docs.microsoft.com/en-us/azure/search/search-create-service-portal#get-a-key-and-url-endpoint)
Once you have the values of the Cognitive Search Service [service endpoint](https://docs.microsoft.com/en-us/azure/search/search-create-service-portal#get-a-key-and-url-endpoint)
and [api key](https://docs.microsoft.com/en-us/azure/search/search-security-api-keys) you can create the Search Service client:

```python
from azure.core.credentials import AzureKeyCredential
from azure.search import SearchServiceClient
from azure.search.documents import SearchServiceClient

credential = AzureKeyCredential("<api key>")

client = SearchServiceClient(endpoint="<service endpoint>"
credential=credential)
credential=credential)
```

### Create a SearchIndexClient
### Create a SearchClient

To create a SearchIndexClient, you will need an existing index name as well as the values of the Cognitive Search Service
[service endpoint](https://docs.microsoft.com/en-us/azure/search/search-create-service-portal#get-a-key-and-url-endpoint) and
To create a SearchClient, you will need an existing index name as well as the values of the Cognitive Search Service
[service endpoint](https://docs.microsoft.com/en-us/azure/search/search-create-service-portal#get-a-key-and-url-endpoint) and
[api key](https://docs.microsoft.com/en-us/azure/search/search-security-api-keys).
Note that you will need an admin key to index documents (query keys only work for queries).

```python
from azure.core.credentials import AzureKeyCredential
from azure.search import SearchIndexClient
from azure.search.documents import SearchClient

credential = AzureKeyCredential("<api key>")

client = SearchIndexClient(endpoint="<service endpoint>",
index_name="<index name>",
credential=credential)
client = SearchClient(endpoint="<service endpoint>",
index_name="<index name>",
credential=credential)
```

## Examples
Expand All @@ -101,36 +101,39 @@ Create a new index
```python
from azure.core.credentials import AzureKeyCredential
from azure.search.documents import SearchServiceClient, CorsOptions, Index, ScoringProfile
client = SearchServiceClient(service_endpoint, AzureKeyCredential(key))
client = SearchServiceClient("<service endpoint>", AzureKeyCredential("<api key>"))

name = "hotels"
fields = [
{
"name": "hotelId",
"type": "Edm.String",
"key": True,
"searchable": False
},
{
"name": "baseRate",
"type": "Edm.Double"
}]
cors_options = CorsOptions(allowed_origins=["*"], max_age_in_seconds=60)
scoring_profiles = []
index = Index(
name=name,
fields=fields,
scoring_profiles=scoring_profiles,
cors_options=cors_options)

result = client.create_index(index)
fields = [
{
"name": "hotelId",
"type": "Edm.String",
"key": True,
"searchable": False
},
{
"name": "baseRate",
"type": "Edm.Double"
}
]
cors_options = CorsOptions(allowed_origins=["*"], max_age_in_seconds=60)
scoring_profiles = []

index = Index(
name=name,
fields=fields,
scoring_profiles=scoring_profiles,
cors_options=cors_options)

result = client.create_index(index)
```

### Upload documents to an index
Add documents (or update existing ones), e.g add a new document for a new hotel:
```python
from azure.core.credentials import AzureKeyCredential
from azure.search import SearchIndexClient
search_client = SearchIndexClient(service_endpoint, index_name, AzureKeyCredential(key))
from azure.search.documents import SearchClient
client = SearchClient("<service endpoint>", "<index_name>", AzureKeyCredential("<api key>"))

DOCUMENT = {
'Category': 'Hotel',
Expand All @@ -140,7 +143,7 @@ DOCUMENT = {
'HotelName': 'Azure Inn',
}

result = search_client.upload_documents(documents=[DOCUMENT])
result = client.upload_documents(documents=[DOCUMENT])

print("Upload of new document succeeded: {}".format(result[0].succeeded))
```
Expand All @@ -149,10 +152,10 @@ print("Upload of new document succeeded: {}".format(result[0].succeeded))
Get a specific document from the index, e.f. obtain the document for hotel "23":
```python
from azure.core.credentials import AzureKeyCredential
from azure.search import SearchIndexClient
search_client = SearchIndexClient(service_endpoint, index_name, AzureKeyCredential(key))
from azure.search.documents import SearchClient
client = SearchClient("<service endpoint>", "<index_name>", AzureKeyCredential("<api key>"))

result = search_client.get_document(key="23")
result = client.get_document(key="23")

print("Details for hotel '23' are:")
print(" Name: {}".format(result["HotelName"]))
Expand All @@ -165,10 +168,10 @@ Search the entire index or documents matching a simple search text, e.g. find
hotels with the text "spa":
```python
from azure.core.credentials import AzureKeyCredential
from azure.search import SearchIndexClient
search_client = SearchIndexClient(service_endpoint, index_name, AzureKeyCredential(key))
from azure.search.documents import SearchClient
client = SearchClient("<service endpoint>", "<index_name>", AzureKeyCredential("<api key>"))

results = search_client.search(query="spa")
results = client.search(query="spa")

print("Hotels containing 'spa' in the name (or other fields):")
for result in results:
Expand All @@ -181,16 +184,16 @@ Get search suggestions for related terms, e.g. find search suggestions for
the term "coffee":
```python
from azure.core.credentials import AzureKeyCredential
from azure.search import SearchIndexClient, SuggestQuery
search_client = SearchIndexClient(service_endpoint, index_name, AzureKeyCredential(key))
from azure.search.documents import SearchClient, SuggestQuery
client = SearchClient("<service endpoint>", "<index_name>", AzureKeyCredential("<api key>"))

query = SuggestQuery(search_text="coffee", suggester_name="sg")

results = search_client.suggest(query=query)
results = client.suggest(query=query)

print("Search suggestions for 'coffee'")
for result in results:
hotel = search_client.get_document(key=result["HotelId"])
hotel = client.get_document(key=result["HotelId"])
print(" Text: {} for Hotel: {}".format(repr(result["text"]), hotel["HotelName"]))
```

Expand All @@ -212,7 +215,7 @@ headers, can be enabled on a client with the `logging_enable` keyword argument:
import sys
import logging
from azure.core.credentials import AzureKeyCredential
from azure.search import SearchIndexClient
from azure.search.documents import SearchClient

# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
Expand All @@ -223,13 +226,14 @@ handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# This client will log detailed information about its HTTP sessions, at DEBUG level
search_client = SearchIndexClient(service_endpoint, index_name, AzureKeyCredential(key), logging_enable=True)
client = SearchClient("<service endpoint>", "<index_name>", AzureKeyCredential("<api key>"), logging_enable=True)

```

Similarly, `logging_enable` can enable detailed logging for a single operation,
even when it isn't enabled for the client:
```python
result = search_client.search(query="spa", logging_enable=True)
result = client.search(query="spa", logging_enable=True)
```

## Next steps
Expand Down