{"id":27333971,"url":"https://github.com/mkalkbrenner/search_api_solr","last_synced_at":"2025-04-12T14:09:00.901Z","repository":{"id":27930496,"uuid":"31422867","full_name":"mkalkbrenner/search_api_solr","owner":"mkalkbrenner","description":null,"archived":false,"fork":false,"pushed_at":"2025-03-14T15:48:08.000Z","size":7944,"stargazers_count":7,"open_issues_count":6,"forks_count":54,"subscribers_count":4,"default_branch":"4.x","last_synced_at":"2025-03-14T16:37:37.928Z","etag":null,"topics":["drupal","php","search","solarium","solr","web"],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mkalkbrenner.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-02-27T14:28:06.000Z","updated_at":"2025-03-14T15:48:12.000Z","dependencies_parsed_at":"2023-10-15T11:20:34.927Z","dependency_job_id":"ece4bec6-71fa-4fa0-89ae-ae415d600b29","html_url":"https://github.com/mkalkbrenner/search_api_solr","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkalkbrenner%2Fsearch_api_solr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkalkbrenner%2Fsearch_api_solr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkalkbrenner%2Fsearch_api_solr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkalkbrenner%2Fsearch_api_solr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mkalkbrenner","download_url":"https://codeload.github.com/mkalkbrenner/search_api_solr/tar.gz/refs/heads/4.x","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248578869,"owners_count":21127713,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["drupal","php","search","solarium","solr","web"],"created_at":"2025-04-12T14:09:00.299Z","updated_at":"2025-04-12T14:09:00.885Z","avatar_url":"https://github.com/mkalkbrenner.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Search API Solr\n\nThis module provides an implementation of the Search API which uses an Apache\nSolr search server for indexing and searching. Before enabling or using this\nmodule, you'll have to carefully read all the instructions given here.\n\nThe minimum support version Solr version is 6.4. Any version below might work\nif you use your own Solr config or if you enable the optional\n`search_api_solr_legacy` sub-module that is included in this module.\n\nIn general, it is highly recommended to run Solr in cloud mode (Solr Cloud)!\n\nFor a full description of the module, visit the\n[project page](https://www.drupal.org/project/search_api_solr).\n\nSubmit bug reports and feature suggestions, or track changes in the\n[issue queue](https://www.drupal.org/project/issues/search_api_solr).\n\nRead the\n[Search API Solr Documentation](https://www.drupal.org/docs/extending-drupal/contributed-modules/contributed-module-documentation/search-api-solr).\n\n\n## Table of contents\n\n- Requirements\n- Installation\n- Local Solr Instance: : Solr Cloud - the modern way\n- Local Solr Instance: : Solr (single core) - the classic way\n- Local Solr Instance: : Solr Cloud - the classic way\n- Using Jump-Start config-sets and docker images\n- Updating Solr\n- Search API Solr features\n- Customizing your Solr server\n- Troubleshooting Views\n- Troubleshooting Facets\n- Development\n- Maintainers\n\n\n## Requirements\n\nThis module requires the [Search API](https://www.drupal.org/project/search_api)\nmodule, as well as several external libraries, which will be installed\nautomatically by Composer, which manages its dependencies.\n\n\n## Installation\n\nInstall as you would normally install a contributed Drupal module. For further\ninformation, see\n[Installing Drupal Modules](https://www.drupal.org/docs/extending-drupal/installing-drupal-modules).\n\nTo connect a Solr server, follow the Search API documentation to add a Search\nAPI Server and select Solr as backend.\n\nThe Search API Solr Backend supports different Solr Connector Plugins. Choose\nand configure the one that matches your requirements. Some Solr service\nproviders require a special connector to be installed as third-party module.\n(See the Connectors section below.)\n\n\n## Local Solr Instance: Solr Cloud - the modern way\n\nTo setup Solr in Cloud mode locally you can either follow the instructions of\nthe [Apache Solr Reference Guide](https://solr.apache.org/guide/) or use\ndocker-compose with\nhttps://github.com/docker-solr/docker-solr-examples/blob/master/docker-compose/docker-compose.yml\n\nThe preferred way for local development is to use DDEV where you can easily add\n[ddev-solr](https://github.com/ddev/ddev-solr) using this command:\n\n    $ ddev get ddev/ddev-solr\n    $ ddev restart\n\nFor Drupal and Search API Solr you need to configure a Search API server using\nSolr as backend and `Solr Cloud with Basic Auth` as its connector. As mentioned\nabove, username \"solr\" and password \"SolrRocks\" are the pre-configured\ncredentials for Basic Authentication in `.ddev/solr/security.json`.\n\nSolr requires a Drupal-specific configset for any collection that should be used\nto index Drupal's content. (In Solr Cloud \"collections\" are the equivalent to\n\"cores\" in classic Solr installations. Actually, in a big Solr Cloud\ninstallation a collection might consist of multiple cores across all Solr Cloud\nnodes.)\n\nStarting from Search API Solr module version 4.2.1 you don't need to deal with\nconfigsets manually anymore. Just enable the `search_api_solr_admin` sub-module\nwhich is part of Search API Solr. Now you create or update your \"collections\" at\nany time by clicking the \"Upload Configset\" button on the Search API server\ndetails page (see installation steps below), or use `drush` to do this with\n\n    $ ddev drush --numShards=1 search-api-solr:upload-configset SEARCH_API_SERVER_ID\n\nNote: Replace `SEARCH_API_SERVER_ID` with your Search API server machine name.\nThe number of \"shards\" should always be \"1\" as this local installation only\nruns a single Solr node.\n\nNote: The `search_api_solr_admin` sub-module and its features are not limited to\nddev! They work with any Solr Cloud instance as long as the required APIs are\nnot blocked by the hosting provider.\n\n### Installation steps\n\n1. Enable the `search_api_solr_admin` module. (This sub-module is included in Search API Solr \u003e= 4.2.1)\n2. Create a search server using the Solr backend and select `Solr Cloud with Basic Auth` as connector:\n   - HTTP protocol: `http`\n   - Solr node: `solr`\n   - Solr port: `8983`\n   - Solr path: `/`\n   - Default Solr collection: `techproducts` (You can define any name here. The\n     collection will be created automatically.)\n   - Username: `solr`\n   - Password: `SolrRocks`\n3. On the server's \"view\" page click the `Upload Configset` button and check the \"Upload (and overwrite) configset\" checkbox.\n4. Set the number of shards to `1`.\n5. Press `Upload`.Once Solr is running with DDEV you don't need to deal with any configset\n\n\n## Local Solr Instance: Solr (single core) - the classic way\n\nIn order for this module to work, you need to set up a Solr server.\nFor this, you can either purchase a server from a web Solr hosts or set up your\nown Solr server on your web server (if you have the necessary rights to do so).\nIf you want to use a hosted solution, a number of companies are listed on the\nmodule's [project page](https://drupal.org/project/search_api_solr). Otherwise,\nplease follow the instructions in this section.\n\nNote: A more detailed set of instructions is available at:\n\n- https://lucene.apache.org/solr/guide/8_4/installing-solr.html\n- https://lucene.apache.org/solr/guide/8_4/taking-solr-to-production.html\n- https://lucene.apache.org/solr/guide/ - list of other version specific guides\n\nAs a pre-requisite for running your own Solr server, you'll need a Java JRE.\n\nDownload the latest version of Solr 8.x from\nhttps://lucene.apache.org/solr/downloads.html and unpack the archive\nsomewhere outside of your web server's document tree. The unpacked Solr\ndirectory is named `$SOLR` in these instructions.\n\nNote: Solr 6.x is still supported by search_api_solr but strongly discouraged.\nThat version has been declared end-of-life by the Apache Solr project and is\nthus no longer supported by them.\n\n**_Before_** creating the Solr core (`$CORE`) you will have to make sure it uses\nthe proper configuration files. They aren't always static but vary on your\nDrupal setup.\n\nBut the Search API Solr Search module will create the correct configs for you!\n\n1. Make sure you have Apache Solr started and accessible (i.e. via port 8983).\n   You can start it without having a core configured at this stage.\n2. Visit Drupal configuration (/admin/config/search/search-api) and create a\n   new Search API Server according to the search_api documentation using\n   \"Solr\" as Backend and the connector that matches your setup.\n   Input the correct core name (which you will create at step 4, below).\n3. Download the config.zip from the server's details page or by using\n   `drush solr-gsc` with proper options, for example for a server named\n   \"my_solr_server\": `drush solr-gsc my_solr_server config.zip 8.4`.\n4. Copy the config.zip to the Solr server and extract. The unpacked\n   configuration directory is named `$CONF` in these instructions.\n\n**_Now_** you can create a Solr core using this config-set on a running Solr\nserver. There are different ways to do so. For most Linux distributions you can\nrun\n\n`$ sudo -u solr $SOLR/bin/solr create_core -c $CORE -d $CONF -n $CORE`\n\nYou will see something like\n\n    $ sudo -u solr /opt/solr/bin/solr create_core -c test-core -d /tmp/solr-conf -n test-core\n\nCopying configuration to new core instance directory:\n/var/solr/data/test-core\n\nIf you're forced to create the core before you can run Drupal to generate the\nconfig-set you could also use the appropriate jump-start config-set you'll\nfind in the _jump-start_ directory of this module.\n\n**You must not create a core without a proper drupal config-set!**\nIf you do so - even by accident - you won't recognize it immediately. But you'll\nrun into trouble like this soon:\n[SolrException: Can not use FieldCache on multivalued field: boost_document](https://www.drupal.org/project/search_api_solr/issues/3056971)\n\nNote: Every time you add a new language to your Drupal instance or add a custom\nSolr Field Type you have to update your core configuration files. Using the\nexample above they will be located in /var/solr/data/test-core/conf. The Drupal\nadmin UI should inform you about the requirement to update the  configuration.\nReload the core after updating the config using\n`curl -k http://localhost:8983/solr/admin/cores?action=RELOAD\u0026core=$CORE` on\nthe command line or enable the search_api_admin sub-module to do it from the\nDrupal admin UI.\n\nNote: There's file called `solrcore.properties` within the set of generated\nconfig files. If you need to fine tune some setting you should do it within this\nfile if possible instead of modifying `solrconf.xml`.\n\nAfterward, go to `http://localhost:8983/solr/#/$CORE` in your web browser to\nensure Solr is running correctly.\n\nCAUTION! For production sites, it is vital that you somehow prevent outside\naccess to the Solr server. Otherwise, attackers could read, corrupt or delete\nall your indexed data. Using the server as described below WON'T prevent this by\ndefault! If it is available, the probably easiest way of preventing this is to\ndisable outside access to the ports used by Solr through your server's network\nconfiguration or through the use of a firewall.\nOther options include adding basic HTTP authentication or renaming the solr/\ndirectory to a random string of characters and using that as the path.\n\nFor configuring indexes and searches you have to follow the documentation of\nsearch_api.\n\n\n## Local Solr Instance: Solr Cloud - the classic way\n\nInstead of a single core you have to create a collection in your Solr Cloud\ninstance. To do so you have to read the Solr handbook.\n\n1. Create a Search API Server according to the search_api documentation using\n   \"Solr\" or \"Multilingual Solr\" as Backend and the \"Solr Cloud\" or\n   \"Solr Cloud with Basic Auth\" Connector.\n1. Download the config.zip from the server's details page or by using\n   `drush solr-gsc`\n1. Deploy the config.zip via zookeeper.\n\n\n### Using Linux specific Solr Packages\n\nNote: The paths where the config.zip needs to be extracted to might differ from\nthe instructions above as well. For some distributions a directory like\n_/var/solr_ or _/usr/local/solr_ exists.\n\n\n## Local Solr Instance: Using Jump-Start config-sets and docker images\n\nThis module contains a _jump-start_ directory where you'll find a\ndocker-compose.yml files for various Solr versions. These use default\nconfig-sets that will work for most drupal use-cases.\nThis variant is suitable for evaluation and development purposes.\n\nThese config-sets are also suitable for standard production use-cases without\nthe need for advanced features or customizations.\n\n![Jump Start Config-Sets](https://github.com/mkalkbrenner/search_api_solr/workflows/Jump%20Start%20Config-Sets/badge.svg?branch=4.x)\n\n\n## Updating Solr\n\nWhenever you update your Solr installation it is recommended that you generate a\nnew config-set and deploy it. The deployment depends on the installation\nvariation you choose before. It is also recommended to re-index yur content\nafter an update. But if it is a minor update it should be safe to just queue all\ncontent for re-indexing.\n\nWhen performing a major version update like from Solr 6 to Solr 8 it is\nrecommended to delete the core or collection and recreate it like described in\nthe installation instructions above.\n\n\n## Search API Solr features\n\nAll Search API datatypes are supported by using appropriate Solr datatypes for\nindexing them.\n\nThe \"direct\" parse mode for queries will result in the keys being directly used\nas the query to Solr using the\n[Standard Parse Mode](https://lucene.apache.org/solr/guide/7_2/the-standard-query-parser.html).\n\nAdding Devel module (and optionally, addons like Kint) provides the site with\na Solr Query Debugger and shows how content gets indexed.\n\nRegarding third-party features, the following are supported:\n\n- autocomplete\n    - Introduced by module: search_api_solr_autocomplete\n    - Lets you add autocompletion capabilities to search forms on the site.\n- facets\n    - Introduced by module: facet\n    - Allows you to create facetted searches for dynamically filtering search\n      results.\n- more like this\n    - Introduced by module: search_api\n    - Lets you display items that are similar to a given one. Use, e.g., to create\n      a \"More like this\" block for node pages build with Views.\n- multisite\n    - Introduced by module: search_api_solr\n- spellcheck\n    - Introduced by module: search_api_solr\n    - Views integration provided by search_api_spellcheck\n- attachments\n    - Introduced by module: search_api_attachments\n- location\n    - Introduced by module: search_api_location\n- NLP\n    - Introduced by module: search_api_solr_nlp\n    - Adds more fulltext field types based on natural language processing, for\n      example field types that filter all word which aren't nouns. This is great\n      for auto-completion.\n\nIf you feel some service option is missing, or have other ideas for improving\nthis implementation, please file a feature request in the project's issue queue,\nat https://drupal.org/project/issues/search_api_solr.\n\n\n### Processors\n\nPlease consider that, since Solr handles tokenizing, stemming and other\npreprocessing tasks, activating any preprocessors in a search index' settings is\nusually not needed or even cumbersome. If you are adding an index to a Solr\nserver you should therefore then disable all processors which handle such\nclassic preprocessing tasks.\n\nIf you create a new index, such processors won't be offered anymore since\n8.x-2.0.\n\nBut the remaining processors are useful and should be activated. For example the\nHTML filter or the Highlighting processor.\n\nBy default, the Highlighting processor provided by Search API uses PHP to create\nhighlighted snippets or an excerpt based on the entities loaded from the\ndatabase. Solr itself can do that much better, especially for different\nlanguages. If you check `Retrieve result data from Solr` and `Highlight\nretrieved data` on the index edit page, the Highlighting processor will use\nthis data directly and bypass it's own logic. To do the highlighting, Solr will\nuse the configuration of the Highlighting processor.\n\n\n### Connectors\n\nThe communication details between Drupal and Solr is implemented by connectors.\nThis module includes:\n  - Standard Connector\n  - BasicAuth Connector\n  - Solr Cloud Connector\n  - Solr Cloud BasicAuth Connector\n\nThere are service provider specific connectors available, for example from\nAcquia, Pantheon, hosted solr, platform.sh, and others:\n  - [Hosted Solr](https://www.drupal.org/project/hosted_solr)\n  - [SearchStax](https://www.drupal.org/project/search_api_searchstax)\n  - [Pantheon](https://www.drupal.org/project/search_api_pantheon)\n  - [Acquia](https://www.drupal.org/project/acquia_search)\n\nPlease contact your provider for details if you don't run your own Solr server.\n\n\n## Customizing your Solr server\n\nIt's highly recommended that you don't modify the schema.xml and solrconfig.xml\nfiles manually because this module dynamically generates them for you.\n\nMost features that can be configured within these config files are reflected\nby drupal configs that could be handled via drupal's own config management.\n\nYou can also create your own Solr field types by providing additional field\nconfig YAML files. Have a look at this module's config folder to see examples.\n\nSuch field types can target a specific Solr version and a \"domain\". For example\n\"Apple\" means two different things in a \"fruits\" domain or a \"computer\" domain.\n\n\n## Troubleshooting Views\n\nWhen displaying search results from Solr in Views using the Search API Views\nintegration, you have the choice to fetch the displayed values from Solr by\nenabling \"Retrieve result data from Solr\" on the server edit page. Otherwise,\nSolr will only return the IDs and Search API loads the values from the database.\n\nIf you decide to retrieve the values from Solr you have to enable \"Skip item\naccess checks\" in the query options in the views advanced settings. Otherwise,\nthe database objects will be loaded again for this check.\nIt's obvious that you have to apply required access checks during indexing in\nthis setup. For example using the corresponding processor or by having different\nindexes for different user roles.\n\nIn general, it's recommended to *disable the Views cache*. By default, the Solr\nsearch index is updated asynchronously from Drupal, and this interferes with the\nViews cache. Having the cache enabled will cause stale results to be shown, and\nnew content might not show up at all.\n\nIn case you really need caching (for example because you are showing some search\nresults on your front page) then you use the 'Search API (time based)' cache\nplugin. This will make sure the cache is cleared at certain time intervals, so\nyour results will remain relevant. This can work well for views that have no\nexposed filters and are set up by site administrators.\n\nSince 8.x-2.0 in combination with Solr 6.6 or higher you can also use the\n'Search API (tag based)' cache. But in this case you need to ensure that you\nenable \"Finalize index before first search\" and \"Wait for commit after last\nfinalization\" in the \"Solr specific index options\".\n\nBut be aware that this will slow down the first search after any modification to\nan index. So you have to choose if no caching or tag based caching in\ncombination with finalization is the better solution for your setup.\nThe decision depends on how frequent index modification happen or how expensive\nyour queries are.\n\nIf you index some drupal fields multiple times in the same index and modify the\nsingle values differently via our API before the values get indexed, you'll\nnotice that Views will randomly output the same value for all of these fields if\nyou enabled \"Retrieve result data from Solr\". In this case you have to enable\nthe \"Solr dummy fields\" processor and add as many dummy fields to the index as\nyou require. Afterward you should manipulate these fields via API.\n\n\n## Troubleshooting Facets\n\nFacetting on fulltext fields is not yet supported. We recommend the use of\nstring fields for that purpose.\n\nTrie based field types were deprecated in Solr 6 and with Solr 7 we switched to\nthe point based equivalents. But lucene doesn't support a mincount of \"0\" for\nthese field types. We recommend the use of string fields instead of numeric ones\nfor that purpose.\n\nIf updating from Search API Solr 8.x-1.x or from Solr versions before 7 to Solr\n7 or 8, check your Search API index' field configurations to avoid these errors\nthat will lead to exceptions and zero results.\n\n\n## Development\n\nWhenever you need to enhance the functionality you should do it using the API\ninstead of extending the SearchApiSolrBackend class!\n\nTo customize connection-specific things you should provide your own\nimplementation of the \\Drupal\\search_api_solr\\SolrConnectorInterface.\n\nA lot of customization can be achieved using YAML files and drupal's\nconfiguration management.\n\nWe leverage the [solarium library](http://www.solarium-project.org/). You can\nalso interact with solarium's API using our hooks and callbacks or via event\nlisteners. This way you can for example add any solr specific parameter to a\nquery you need.\n\nBut if you create Search API Queries by yourself in code there's an easier way.\nYou can simply set the required parameter as option prefixed by 'solr_param_'.\n\nSo these two lines are \"similar\":\n\n    $search_api_query-\u003esetOption('solr_param_mm', '75%');\n\n    $solarium_query-\u003esetParam('mm', '75%');\n\n\n### Patches and Issues Workflow\n\nOur test suite includes integration tests that require a real Solr server. This\nrequirement can't be provided by the drupal.org test infrastructure.\nTherefore, we leverage github workflows for our tests and had to establish a\nmore complex workflow:\n\n1. Open an issue on drupal.org as usual\n2. Upload the patch for being reviewed to that issue on drupal.org as usual\n3. Fork https://github.com/mkalkbrenner/search_api_solr\n4. Apply your patch and file a PR on github\n5. Add a link to the github PR to the drupal.org issue\n\nThe PR on github will automatically be tested on github and the test results\nwill be reflected in the PR conversation.\n\n\n### Running the test suite locally\n\nThis module comes with a suite of automated tests. To execute those, you just\nneed to have a (correctly configured) Solr instance running at the following\naddress:\n\n    http://localhost:8983/solr/drupal\n\nThis represents a core named \"drupal\" in a default installation of Solr.\n\nAs long as you're changes don't modify the config-set generation you could\nleverage docker, too. You'll find ready to use docker-compose files in the\n_jump-start_ directory.\n\nThe tests themselves could be started by running something like this in your\ndrupal folder:\n\n    $ phpunit -c core --group search_api_solr\n\n(The exact command varies on your setup and paths.)\n\n\n## Maintainers\n\n- Markus Kalkbrenner - [mkalkbrenner](https://www.drupal.org/u/mkalkbrenner)\n- Thomas Seidl - [drunken monkey ](https://www.drupal.org/u/drunken-monkey)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmkalkbrenner%2Fsearch_api_solr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmkalkbrenner%2Fsearch_api_solr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmkalkbrenner%2Fsearch_api_solr/lists"}