Configuration
Your Opensolr index is powered by a set of configuration files. These files tell your index how to understand your data, which words to treat as synonyms, which words to ignore, and much more. This page explains each file, how to edit them, and how to upload new ones. For a deeper look at how all configuration files relate to each other, see Configuration Files Dependency Flow.
Your Configuration Files
Think of these files as the "brain settings" for your search engine. Each one controls a specific aspect of how your index works:
What Each File Does
schema.xml
The most important file. It defines every field in your index: names, types (text, number, date), and how text is analyzed (stemming, lowercasing, etc.). When you add a new kind of data, you typically edit this file first. Learn how to add fields in the How to Define New Fields in schema.xml guide.
solrconfig.xml
Controls the engine itself. How search queries are processed, how caching works, when auto-commit triggers, and which search features are enabled. Advanced users tune this for performance.
synonyms.txt
Teaches your search engine that certain words mean the same thing. If a user searches for "sofa" they also find results containing "couch." One line per synonym group, separated by commas.
stopwords.txt
Lists common words that should be ignored during search — words like "the," "a," "is," and "of." Removing these speeds up searches and improves relevance because they appear in almost every document.
protwords.txt
Protected words are shielded from stemming and other text processing. "Running" normally becomes "run," but if you protect "Running" it stays exactly as-is. Perfect for brand names, technical terms, and acronyms.
elevate.xml
Pin specific documents to the top of search results for specific queries. When someone searches for "returns" you can guarantee your return policy page appears first. Managed through the Query Elevation page.
Built-in Code Editor
Opensolr includes a full code editor right in your browser. No need to download files, edit them locally, and re-upload. Just open the file, make your changes, and save.
Editor Features
- Syntax highlighting — XML tags, attributes, and values are color-coded so you can spot errors easily
- Line numbers — every line is numbered for easy reference and debugging
- Direct save — click Save and your changes are written to the file immediately
- All files accessible — switch between any configuration file using the file dropdown
- Go to your Dashboard and select an index
- Click the Configuration tab
- Choose a file from the dropdown (e.g.,
schema.xml) - Edit the file content directly in the browser editor
- Click Save to write your changes
- Click Reload (in the Tools tab) to apply the changes to your live index
Uploading Files
You can also upload configuration files from your computer. This is useful when you have files prepared locally or want to copy a configuration from another index.
Upload Individual File
Upload a single configuration file. Select the file from your computer, and it replaces the existing version on the server. Works for any of the supported config files. To upload via the API, see API: Upload Config Files.
Upload ZIP Archive
Upload multiple configuration files at once inside a ZIP archive. Opensolr extracts the files and puts each one in the right place. Perfect for migrating a full configuration. See API: Upload via ZIP Archive for the programmatic approach.
ZIP archives must be under 1 MB total. Individual files inside the ZIP must each be under 500 KB. A ZIP may contain at most 260 files. These limits prevent accidental uploads of enormous files that could affect performance.
The Configuration Workflow
Whenever you change a configuration file, follow this simple process to make your changes take effect:
Saving a configuration file only writes it to disk. Your running index does not know about the changes yet. You must go to the Index Tools page and click Reload for the changes to take effect. Without reloading, your old configuration is still active.
Tips for Editing Configuration Files
Before making significant edits to schema.xml or solrconfig.xml, download a copy of the current file first. If something goes wrong, you can upload the backup to restore it.
XML files like schema.xml are strict about formatting. Every opening tag needs a closing tag, attribute values need quotes, and special characters (&, <) need escaping. A single typo can prevent your index from reloading.
In synonyms.txt, put each group of synonyms on its own line. Separate words with commas: fast, quick, speedy, rapid. Lines starting with # are treated as comments.
After editing and reloading, run a few searches to make sure everything still works as expected. This catches errors early before they affect your users.
Common Fields in schema.xml
Here are some of the most commonly used fields. Your index might have more depending on your data:
| Field Name | Type | What It Stores |
|---|---|---|
id |
string | Unique identifier for each document (required) |
title |
text | The title or headline of the document |
text |
text | The main body content (usually the largest field) |
uri |
string | The URL or unique path of the document |
timestamp |
date | When the document was added or last updated |
description |
text | A short summary or meta description |
Opensolr schemas include dynamic field patterns like *_s (string), *_t (text), *_i (integer), and *_dt (date). Any field matching these patterns is automatically created with the right type — no schema editing needed. Just send data with a field name like category_s and it works. If your index uses managed-schema instead of schema.xml, see How to Move from managed-schema to schema.xml.
Learn about applying config changes with Index Tools (Reload), or explore Search Tuning for adjusting how search results are ranked. You can also list all your configuration files via the API.