[[app-search-api]]
== App Search API

This document includes examples for different API requests. Please refer to the https://www.elastic.co/guide/en/app-search/current/index.html[Elastic App Search Documentation] for more information, particularly the https://www.elastic.co/guide/en/app-search/current/api-reference.html[API Reference].

=== Engines

[source,rb]
----------------------------
# Create an engine
client.create_engine(name: 'videogames')

# List all engines
client.list_engines

# Get an engine
client.engine('videogames')

# Delete an engine
client.delete_engine('videogames')
----------------------------

=== Meta engines

[source,rb]
----------------------------
# Create a meta engine:
body = {
  name: engine_name,
  type: 'meta',
  source_engines: [ 'books', 'videogames' ]
}
client.create_engine(name: engine_name, body: body)

# Add a source engine to a meta engine:
client.add_meta_engine_source(meta_engine_name, source_engines: ['engine1', 'engine2'])

# Remove a source enginge from a meta engine:
client.delete_meta_engine_source(meta_engine_name, source_engines: ['engine1', 'engine2'])
----------------------------

=== Documents

[source,rb]
----------------------------
engine_name = 'videogames'
document = {
  id: 'Mr1064',
  name: 'Super Luigi 64',
  body: 'A classic 3D videogame'
}

# Index documents
client.index_documents(engine_name, documents: document)

# List documents
client.list_documents(engine_name)

# Get document(s) by ID:
client.documents(engine_name, document_ids: [id1, id2])

# Delete a document
client.delete_documents(engine_name, document_ids: [document_id])

# Update a document
client.put_documents(engine_name, documents: [{id: document_id, key: value}])
----------------------------

=== Search

[source,rb]
----------------------------
# Single Search
query = {
  query: 'luigi'
}

client.search(engine_name, query)

# Search with multiple filters
client.search('parks', {
  body: {
    query: "olympic",
    filters: {
      all: [
        { states: "Washington" },
        { world_heritage_site: "true" }
      ]
    }
  }
})

# Multi query search
queries = [{ query: 'Nicanor'}, { query: 'Iain' }]

client.multi_search(engine_name, body: queries)

----------------------------

=== Synonym Sets

[source,rb]
----------------------------
# Create a synonym set
client.create_synonym_set(engine_name, body: {['synonym1', 'synonym2']})

# List synonym sets
client.list_synonym_sets(engine_name)

# Retrieve a synonym set by id
client.synonym_set(engine_name, synonym_set_id: 'id')

# Update a synonym set by id
client.put_synonym_set(engine_name, synonym_set_id: 'id', body: {synonyms: ['synonym2', 'synonym3']})

# Delete a synonym set
client.delete_synonym_set(engine_name, synonym_set_id: id)
----------------------------

=== Curations

[source,rb]
----------------------------
# Create a curation
client.create_curation(
         engine_name,
         queries: ['query1'],
         promoted: ['doc-id1'],
         hidden: ['doc-id2']
       )

# Retrieve a curation by id:
client.curation(engine_name, curation_id: 'cur-id')

# Update an existing curation:
client.put_curation(
  engine_name,
  curation_id: 'cur-id',
  queries: ['query1'],
  promoted: ['doc-id2'],
  hidden: ['doc-id1']
)

# List existing curations:
client.list_curations(engine_name)

# Delete a curation:
client.delete_curation(engine_name, curation_id: 'cur-id')
----------------------------

=== Api Key

[source,rb]
----------------------------
# Create API Key
body = {
  name: name,
  type: 'private',
  read: true,
  write: true,
  access_all_engines: true
}
response = client.create_api_key(body: body)

# Get the details of an API Key
client.api_key(api_key_name: name)

# List API Keys
client.list_api_keys

# Update an API Key
body = { name: name, type: 'private', read: true, write: true, engines: ['test'] }
client.put_api_key(api_key_name: name, body: body)

# Delete an API Key
client.delete_api_key(api_key_name: name)
----------------------------

=== Web Crawler

[CAUTION]
====
The Elastic Enterprise Search web crawler API is a *beta* feature.
Beta features are subject to change and are not covered by the support SLA of general release (GA) features.
Elastic plans to promote this feature to GA in a future release.
====

See https://www.elastic.co/guide/en/app-search/current/web-crawler-api-reference.html[Web Crawler API reference] for more information.

[source,rb]
----------------------------
# Create a crawler domain
body = { name: 'https://www.elastic.co' }
client.create_crawler_domain(engine_name, body: body)

# Get crawler domain information
client.crawler_domain(engine_name, domain_id: domain_id)

# List crawler domains
client.list_crawler_domains(engine_name)

# Update a crawler domain
body = { name: 'https://www.wikipedia.org' }
client.put_crawler_domain(engine_name, domain_id: domain_id, domain: body)

# Delete a crawler domain
client.delete_crawler_domain(engine_name, domain_id: domain_id)

# Create a crawler crawl request
client.create_crawler_crawl_request(engine_name)

# Retrieve a crawl request
client.crawler_crawl_request(engine_name, crawl_request_id: request_id)

# Retrieve active crawl request details
client.crawler_active_crawl_request(engine_name)

# List crawl requests
client.list_crawler_crawl_requests(engine_name)

# Delete an active crawl request
client.delete_active_crawl_request(engine_name)

# Set a crawler crawl schedule
body = { frequency: 1, unit: 'day' }
client.put_crawler_crawl_schedule(engine_name, body: body)

# Retrieve crawler crawl schedule
client.crawler_crawl_schedule(engine_name)

# Delete a crawler crawl schedule
client.delete_crawler_crawl_schedule(engine_name)

# Create a crawler entry point
client.create_crawler_entry_point(engine_name, domain_id: domain_id, body: { value: '/elastic-stack' })

# Update a crawler entry point
client.put_crawler_entry_point(
  engine_name,
  domain_id: domain_id,
  entry_point_id: entry_point_id,
  body: { value: '/enterprise-search' }
)

# Validate a URL
client.crawler_url_validation_result(engine_name,  url: name)

# Extract ccontent from a URL
client.crawler_url_extraction_result(engine_name, url: name)

# Retrieve tracing history for a crawler URL
client.crawler_url_tracing_result(engine_name, url: name)

# Delete a crawler entry point
client.delete_crawler_entry_point(
  engine_name,
  domain_id: domain_id,
  entry_point_id: entry_point_id
)

# Retrieve crawler metrics
client.crawler_metrics

# Retrieve crawler configuration overview
client.crawler_overview(engine_name)

# Create a crawler sitemap
body = { url: 'https://www.elastic.co/sitemap.xml' }
client.create_crawler_sitemap(engine_name, domain_id: domain_id, body: body)

# Update a crawler sitemap
body = { url: 'https://www.elastic.co/sitemap2.xml' }
client.put_crawler_sitemap(engine_name, domain_id: domain_id, sitemap_id: sitemap_id, body: body)

# Delete a crawler sitemap
client.delete_crawler_sitemap(engine_name, domain_id: domain_id, sitemap_id: sitemap_id)

# Create a crawler crawl rule
body = { order: 1, policy: 'allow', rule: 'contains', pattern: '/stack' }
client.create_crawler_crawl_rule(engine_name, domain_id: domain_id, body: body)

# Update a crawler crawl rule
body = { order: 2, policy: 'allow', rule: 'begins', pattern: '/stack' }
client.put_crawler_crawl_rule(engine_name, domain_id: domain_id, crawl_rule_id: rule_id, body: body)

# Delete a crawler crawl rule
client.delete_crawler_crawl_rule(engine_name, domain_id: domain_id, crawl_rule_id: rule_id)

# Create a process crawl
client.create_crawler_process_crawl(engine_name, body: { dry_run: true })

# Retrieve a process crawl
client.crawler_process_crawl(engine_name, process_crawl_id: id)

# Retrieve denied URLs cor a process crawl
client.denied_urls(engine_name, process_crawl_id: id)

# List process crawls
client.list_crawler_process_crawls(engine_name)

# View denied urls for Process Crawl
client.crawler_process_crawl_denied_urls(engine_name, process_crawl_id: id)

# Cancel an active crawl request, stopping a running crawl if needed.
client.delete_crawler_active_crawl_request(engine_name)
----------------------------
=== Adaptive Relevance


The adaptive relevance API is a **beta** feature. Beta features are subject to change and are not covered by the support SLA of general release (GA) features. Elastic plans to promote this feature to GA in a future release. The adaptive relevance API is not available at all Elastic subscription levels. Refer to the Elastic subscriptions pages for https://www.elastic.co/subscriptions/cloud[Elastic Cloud] and https://www.elastic.co/subscriptions[self-managed] deployments.

[source,rb]
----------------------------
# Retrieve adaptive relevance settings
client.adaptive_relevance_settings(engine_name)

# Update adaptive relevance settings for an engine
body = { curation: { enabled: true } }
client.put_adaptive_relevance_settings(engine_name, body: body)

# List suggestions
client.list_adaptive_relevance_suggestions(engine_name)

# Update adaptive relevance
client.put_adaptive_relevance_suggestions(engine_name, body: body)

# Retrive adaptive relevance
client.adaptive_relevance_suggestions(engine_name, search_suggestion_query: 'suggestion')
----------------------------

=== Other API Endpoints

[source,rb]
----------------------------
# Count analytics - Returns the number of clicks and total number of queries over a period
client.count_analytics(engine_name)

# Schema - Retrieve current schema for the engine
client.schema(engine_name)

# Update schema for an engine
client.put_schema(engine_name, schema: {field: 'type'})

# Logs - The API Log displays API request and response data at the Engine level
client.api_logs(engine_name, from_date: Date.new(2020, 10, 01), to_date: Date.new(2020, 11, 05))

# Queries Analytics - Returns queries analytics by usage count
client.top_queries_analytics(engine_name)

# Clicks Analytics - Returns the number of clicks received by a document in descending order
client.top_clicks_analytics(engine_name, query: {})

# Search Settings - Returns current search settings for an engine
client.search_settings(engine_name)

# Update Search Settings
client.put_search_settings(engine_name, body: body)

# Reset search settings
# Warning: This means your settings are wiped! Back them up!
client.reset_search_settings(engine_name)

# Click - Send data about clicked results
client.log_clickthrough(engine_name, body: { query: 'query', document_id: 'doc-id' })

# Query Suggestion - Provide relevant query suggestions for incomplete queries
client.query_suggestion(engine_name, query: 'incomplete_query')
----------------------------
