Package: elastic-site-search
A first-party Python client for theElastic Site Search API.ContentsGetting startedUsageRunning testsFAQContributeLicenseGetting started 🐣You can install the latest version of the Elastic Site Search client usingpip:pipinstallelastic-site-searchTo install locally, clone this repository,cdinto the directory and run:pythonsetup.pyinstallNote:This client has been developed for theElastic Site SearchAPI endpoints only. You may refer to theElastic Site Search API Documentationfor additional context.UsageCreateElastic Site Search accountand get your API key from yourAccount Settings.Configure your client:fromelastic_site_searchimportClientclient=Client(api_key='YOUR_API_KEY')Create anEnginenamed e.g.youtube:engine=client.create_engine('youtube')Create yourDocumentTypes:client.create_document_type('youtube','videos');client.create_document_type('youtube','channels');IndexingNow you need to create yourDocuments. It's very important to think about the type of each field you create aDocument. TheDocumentTypetheDocumentbelongs to will remember each fields type and it is not possible to change it. The type specifies a fields features and you should choose them wisely. For details please have a look at ourField Types Documentation.Add aDocumentto thevideosDocumentType:client.create_document('youtube','videos',{'external_id':'external_id1','fields':[{'name':'title','value':'Site Search Demo','type':'string'},{'name':'tags','value':['Site Search','Search','Full text search'],'type':'string'},{'name':'url','value':'http://www.youtube.com/watch?v=pITuOcGgpBs','type':'enum'},{'name':'category','value':['Tutorial','Product'],'type':'enum'},{'name':'publication_date','value':'2012-05-08T12:07Z','type':'date'},{'name':'likes','value':31,'type':'integer'},{'name':'length','value':1.50,'type':'float'}]})Add aDocumentto thechannelsDocumentType:client.create_document('youtube','channels',{'external_id':'external_id1','fields':[{'name':'title','value':'Elastic','type':'string'},{'name':'url','value':'http://www.youtube.com/user/elasticsearch','type':'enum'},{'name':'video_views','value':15678,'type':'integer'},{'name':'video_counts','value':6,'type':'integer'}]})SearchingNow yourEngineis ready to receive queries. By default, search queries will match any fields that are of typestringortext. You can search eachDocumentTypeindividually:video_results=client.search_document_type('youtube','videos','site search')channel_results=client.search_document_type('youtube','channels','site search')or search allDocumentTypes on yourEngineat once:results=client.search('youtube','site search')AutocompleteFinally, as with full-text searches, you may perform autocomplete-style (prefix match) searches as well:results=client.suggest('youtube','sit')orresults=client.suggest_document_type('youtube','videos','sit')API DocumentationConfiguration:Before issuing commands to the API, configure the client with your API key:fromelastic_site_searchimportClientclient=Client(api_key='YOUR_API_KEY')You can find your API key in yourAccount Settings.SearchIf you want to search for e.g.site searchon yourEngine, you can use:results=client.search('youtube','site search')To limit the search to only thevideosDocumentType:results=client.search_document_type('youtube','videos','site search')Both search methods allow you to specify options as an extra parameter to e.g. filter or sort on fields. For more details on these options please have a look at theSearch Options. Here is an example for showing onlyvideosthat are in thecategoryTutorial:results=client.search_document_type('youtube','videos','site search',{'filters':{'videos':{'category':'Tutorial'}}})AutocompleteAutocompletes have the same functionality as searches. You can autocomplete using all documents:results=client.suggest('youtube','sit')or just for one DocumentType:results=client.suggest_document_type('youtube','videos','sit')or add options to have more control over the results:results=client.suggest('youtube','sit',{'sort_field':{'videos':'likes'}})EnginesRetrieve everyEngine:engines=client.enginesCreate a newEnginewith the nameyoutube:engine=client.create_engine('youtube')Retrieve anEnginebyslugorid:engine=client.engine('youtube')To delete anEngineyou need theslugor theidfield of anengine:client.destroy_engine('youtube')Document TypesRetrieveDocumentTypess of theEnginewith theslugfieldyoutube:document_types=client.document_types('youtube')Show the second batch of documents:document_types=client.document_types('youtube',2)Create a newDocumentTypefor anEnginewith the namevideos:document_type=client.create_document_type('youtube','videos')Retrieve anDocumentTypebyslugorid:document_type=client.document_type('youtube','videos')Delete aDocumentTypeusing theslugoridof it:client.destroy_document_type('youtube','videos')DocumentsRetrieve allDocuments ofEngineyoutubeandDocumentTypevideos:documents=client.documents('youtube','videos')Retrieve a specificDocumentusing itsidorexternal_id:document=client.document('youtube','videos','external_id1')Create a newDocumentwith mandatoryexternal_idand user-defined fields:document=client.create_document('youtube','videos',{'external_id':'external_id1','fields':[{'name':'title','value':'Site Search Demo','type':'string'},{'name':'tags','value':['Site Search','Search','Full text search'],'type':'string'},{'name':'url','value':'http://www.youtube.com/watch?v=pITuOcGgpBs','type':'enum'},{'name':'category','value':['Tutorial','Product'],'type':'enum'},{'name':'publication_date','value':'2012-05-08T12:07Z','type':'date'},{'name':'likes','value':31,'type':'integer'},{'name':'length','value':1.50,'type':'float'}]})Create multipleDocuments at once and return status for eachDocumentcreation:stati=client.create_documents('youtube','videos',{'external_id':'external_id1','fields':[{'name':'title','value':'Site Search Demo','type':'string'},{'name':'tags','value':['Site Search','Search','Full text search'],'type':'string'},{'name':'url','value':'http://www.youtube.com/watch?v=pITuOcGgpBs','type':'enum'},{'name':'category','value':['Tutorial','Product'],'type':'enum'},{'name':'publication_date','value':'2012-05-08T12:07Z','type':'date'},{'name':'likes','value':27,'type':'integer'},{'name':'length','value':1.50,'type':'float'}]},{'external_id':'external_id2','fields':[{'name':'title','value':'Site Search Search Wordpress Plugin Demo','type':'string'},{'name':'tags','value':['Site Search','Search','Full text search','WordPress'],'type':'string'},{'name':'url','value':'http://www.youtube.com/watch?v=rukXYKEpvS4','type':'enum'},{'name':'category','value':['Tutorial','Wordpress'],'type':'enum'},{'name':'publication_date','value':'2012-08-15T09:07Z','type':'date'},{'name':'likes','value':2,'type':'integer'},{'name':'length','value':2.16,'type':'float'}]})Update fields of an existingDocumentspecified byidorexternal_id:client.update_document('youtube','videos','external_id1',{'likes':28,'category':['Tutorial','Search']})Update multipleDocuments at once:stati=client.update_documents('youtube','videos',[{'external_id':'2','fields':{'likes':29}},{'external_id':'3','fields':{'likes':4}}])Create or update aDocument:document=client.create_or_update_document('youtube','videos',{'external_id':'external_id3','fields':[{'name':'title','value':'Site Search Install Type 1: Show results in an overlay','type':'string'},{'name':'tags','value':['Site Search','Search','Full text search','Web'],'type':'string'},{'name':'url','value':'http://www.youtube.com/watch?v=mj2ApIx3frs','type':'enum'}]})Create or update multipleDocumentsat once:stati=client.create_or_update_documents('youtube','videos',{'external_id':'external_id4','fields':[{'name':'title','value':'Site Search Install Type 2: Show results on the current page','type':'string'},{'name':'tags','value':['Site Search','Search','Full text search','Web'],'type':'string'},{'name':'url','value':'http://www.youtube.com/watch?v=6uaZXYK2WOE','type':'enum'}]},{'external_id':'external_id5','fields':[{'name':'title','value':'Site Search Install Type 3: Show results on a new page','type':'string'},{'name':'tags','value':['Site Search','Search','Full text search','Web'],'type':'string'},{'name':'url','value':'http://www.youtube.com/watch?v=ebSWAscBPtc','type':'enum'}]})Destroy aDocument:client.destroy_document('youtube','videos','external_id5')Destroy multipleDocuments at once:stati=client.destroy_documents('youtube','videos',['external_id2','external_id3','external_id6'])DomainsRetrieve allDomains ofEnginewebsites:domains=client.domains('websites')Retrieve a specificDomainbyid:domain=client.domain('websites','generated_id')Create a newDomainwith the URLhttps://elastic.coand start crawling:domain=client.create_domain('websites','https://elastic.co')Delete aDomainusing itsid:client.destroy_domain('websites','generated_id')Initiate a recrawl of a specificDomainusing itsid:client.recrawl_domain('websites','generated_id')Add or update a URL for aDomain:client.crawl_url('websites','generated_id','https://elastic.co/new/path/about.html')AnalyticsTo get the amount of searches on yourEnginein the last 14 days use:searches=client.analytics_searches('youtube')You can also use a specific start and/or end date:searches=client.analytics_searches('youtube','2013-01-01','2013-02-01')To get the amount of autoselects (clicks on autocomplete results) use:autoselects=client.analytics_autoselects('youtube')As with searches you can also limit by start and/or end date:autoselects=client.analytics_autoselects('youtube',2,10)If you are interested in the top queries for yourEngineyou can use:top_queries=client.analytics_top_queries('youtube')To see more top queries you can paginate through them using:top_queries=client.analytics_top_queries('youtube',page=2)Or you can get the top queries in a specific date range:top_queries=client.analytics_top_queries_in_range('youtube','2013-01-01','2013-02-01')If you want to improve you search results, you should always have a look at search queries, that return no results and perhaps add some Documents that match for this query or use our pining feature to add Documents for this query:top_no_result_queries=client.analytics_top_no_result_queries('youtube')You can also specify a date range for no result queries:top_no_result_queries=client.analytics_top_no_result_queries('youtube','2013-01-01','2013-02-01')Running Testspipinstall-rtest_requirements.txt
pythontests/test_client.pyFAQ 🔮Where do I report issues with the client?If something is not working as expected, please open anissue.Where can I learn more about Site Search?Your best bet is to read thedocumentation.Where else can I go to get help?You can checkout theElastic Site Search community discuss forums.Contribute 🚀We welcome contributors to the project. Before you begin, a couple notes...Before opening a pull request, please create an issue todiscuss the scope of your proposal.Please write simple code and concise documentation, when appropriate.License 📗Apache 2.0©ElasticThank you to all thecontributors!