# Search Commands: Subsearch and Append

> Chapter 2 of the Courseiva SPLUNK-CORE-CERTIFIED-POWER-USER curriculum — https://courseiva.com/learn/splunk-core-certified-power-user/search-commands-subsearch-and-append

**Official objective:** 1.2 — Use subsearch and append commands to combine and compare data from multiple searches.

## Introduction

What is the fastest way to filter data using results from another search without writing a complicated script? In Splunk, the subsearch and append commands let you combine and compare data from multiple searches in a single query, saving you time and reducing mistakes. For the SPLK-1003 exam, mastering these commands is crucial because they appear in multiple-choice and hands-on scenario questions that test your ability to correlate events across different data sources.

## The Two-Refrigerator Kitchen Analogy

Have you ever tried to make a big dinner and realised you need to check both the pantry fridge and the garage freezer for ingredients, but you don't want to walk back and forth a dozen times?

Here is the situation: you are cooking a dish that calls for 'any vegetable that is not expired and also appeared in last week's meal plan'. To find this, you first need to look at the garage freezer (where you store meal-plan lists) to find out which vegetables were on last week's plan. Then, armed with that list, you walk to the pantry fridge and check each vegetable's expiry date. You are combining results from two different places in one go.

That is exactly what a subsearch does in Splunk. The inner search (garage freezer) runs first, producing a list of results. The outer search (pantry fridge) then uses that list to filter its own results. It is one query nesting inside another.

Now imagine you have two separate shopping lists, each from a different store. You do not want to merge them; you just want to see them one after the other on the same piece of paper. That is the append command. It runs two independent searches and stacks their results vertically, like two receipts stapled together.

So subsearch is about using one search's output as the input filter for another, while append is about joining results from separate searches into one unified view without them interfering with each other.

## Core explanation

Let us start with the big idea. In Splunk, a search normally runs over your data and returns results. But sometimes you need to use the results of one search to narrow down the results of another search. That is where subsearch comes in. A subsearch is a search within a search. You write it using square brackets [ ] and place it inside the main search. Splunk runs the subsearch first, collects its output (usually a list of values), and then feeds that output into the main search as if you had typed those values yourself.

For example, imagine you are a security analyst and you want to find all login events from users who have been flagged in a 'suspicious_users' lookup table. Instead of first manually looking up those users and then typing them into a new search, you write: index=main sourcetype=login user IN [search index=lookup suspicious_users | fields user]. The subsearch inside the brackets runs first, gets the list of suspicious users, and the outer search then finds only login events for those specific users.

The subsearch has limits. By default, it returns a maximum of 50,000 results. If your subsearch would return more than that, Splunk truncates it. This is a common exam trap. Another limit is the time range: the subsearch inherits the time range of the outer search unless you explicitly set a different one. If you forget, your subsearch might look at the wrong time window.

Now let us talk about append. The append command does something different. It lets you run two independent searches and combine their results into a single table, stacked vertically. Think of it as saying: 'Run search A, then run search B, and show me all the rows from A followed by all the rows from B.' Crucially, with append, the second search does not filter the first one. They are separate streams.

Here is a typical use. You want to compare yesterday's error count with today's error count side by side. You write: index=main sourcetype=errors earliest=-1d@d latest=@d | stats count as TodayErrors | append [search index=main sourcetype=errors earliest=-2d@d latest=-1d@d | stats count as YesterdayErrors]. The first search gets today's errors, the second search (the subsearch inside the brackets) gets yesterday's errors, and append stacks them. The result is a table with one row for today and one row for yesterday.

Keep in mind that append does not merge columns. If the two searches produce different field names, you will get separate columns. In the example above, both searches produce a field called 'count', so they will appear in the same column if you rename them consistently. If you want to put them side by side rather than stacked, you would use a different command like 'appendcols'.

Why do these commands matter? Without them, you would have to run multiple searches manually, copy-paste results, or write complex join statements. Subsearch and append let you do everything in one query, which is faster, less error-prone, and easier to reproduce. They are fundamental building blocks for any Splunk power user.

Let us define key terms you will see in the exam:

- Subsearch: A nested search inside square brackets that runs first and provides input to the outer search.
- Outer search: The main search that contains the subsearch. It uses the subsearch's results as a filter.
- Append: A command that runs a separate search and stacks its results below the main search's results.
- Time range inheritance: The subsearch automatically uses the same time range as the outer search unless you override it.
- Result limits: The maximum number of results a subsearch can return (default 50,000).
- Field name mismatch: When the two searches in an append produce different column names, leading to sparse tables.

Now, how do they work together in practice? You can use a subsearch inside an append, but the subsearch is only used to filter the second search, not the first. For example: index=main sourcetype=login | stats count by user | append [search index=main sourcetype=error user IN [search index=main sourcetype=alert | fields user]]. This is more advanced, but the exam expects you to understand the nesting rules.

A critical point for the exam: subsearch can be slow if the inner search returns many results. Splunk has to run it first, then use those results in the outer query. If possible, use a lookup or join for large datasets. But for smaller sets, subsearch is elegant.

Finally, remember that append returns all results from both searches, even if there are duplicates. If you want to remove duplicates, you need to use 'dedup' afterwards.

## Real-world context

Consider a real IT operations team at a mid-sized e-commerce company. They use Splunk to monitor their website and backend services. One day, the site slows down. The team needs to find out if the slowdown is related to failed payment transactions from certain users who have been flagged for suspicious activity.

The IT professional, let us call her Priya, writes a single query using subsearch. She starts with the outer search: index=main sourcetype=payment_logs latency>5000. This finds slow payments. Then she adds a subsearch: user IN [search index=main sourcetype=flag_logs status=suspicious | fields user]. The inner search first retrieves all users flagged as suspicious. Then the outer search only returns slow payments from those users. With one query, Priya identifies the root cause: a specific group of flagged users are triggering a bug in the payment gateway.

Now imagine a different day. The operations manager wants a weekly report comparing login success rates across two different data centres: DC-East and DC-West. Priya uses append. She writes: index=main sourcetype=login data_center=DC-East | stats count as EastLogins | append [search index=main sourcetype=login data_center=DC-West | stats count as WestLogins]. The result is a tiny table with two rows, one for each data centre. She can then export this to a dashboard.

Here is a step-by-step breakdown of what Priya does:

- First, she defines the time range for the whole search (say, last 24 hours).
- Second, she writes the outer search for DC-East.
- Third, she writes the subsearch for DC-West inside the append brackets.
- Fourth, she runs the query and checks that both rows appear.
- Fifth, she renames the count fields to make the table clear.
- Finally, she schedules the search to run daily and emails the report.

Without subsearch and append, Priya would have to run four separate searches (two for flagged users, one for DC-East, one for DC-West), copy results into a spreadsheet, and manually combine them. That is error-prone and takes 20 minutes instead of 2. The commands save her time and eliminate manual mistakes.

Another common scenario is compliance auditing. A company needs to show that no employee with a terminated contract accessed the system after their last day. Priya writes a subsearch: index=main sourcetype=access_logs | where employee NOT IN [search index=hr sourcetype=termination_logs | fields employee_id]. This finds all access events for employees who are not in the termination list. The subsearch returns a list of terminated employees, and the outer search excludes them. If the subsearch returns too many results, the limit might cause some terminated employees to be missed. Priya knows this and uses a lookup table instead for large datasets.

The key lesson: in the real world, you use subsearch when you need to filter one dataset based on another, and you use append when you need to compare results from separate datasets side by side. These are daily tools for any Splunk power user.

## Exam focus

The SPLK-1003 exam tests subsearch and append in several specific ways. You need to know the exact syntax, the default limits, and the common pitfalls. Here is what to expect.

First, multiple-choice questions about subsearch behaviour. They love to ask: 'What happens if a subsearch returns more than the default limit?' The answer: Splunk truncates the results. The default limit is 50,000 events. A common trap is assuming it returns all results.

Second, they test time range inheritance. A typical question: 'A subsearch runs with no explicit time range. What time range does it use?' The correct answer: it inherits the time range of the outer search. They may set a trap by saying it uses the 'All time' range.

Third, they ask about the difference between subsearch and append. Look for wording like: 'Which command would you use to filter results from one search based on the output of another search?' Subsearch. 'Which command would you use to combine results from two unrelated searches into one table?' Append.

Fourth, they test syntax. One question might show a broken query: index=main [search index=other | fields user] OR [search index=third | fields user]. Is this valid? No, because you cannot have two subsearches without a logical operator. The correct syntax would use OR or IN.

Fifth, they test the use of 'fields' in subsearches. A subsearch must output only the field you want to use for filtering. If you forget 'fields user', the subsearch returns all fields and the outer search may fail or produce unexpected results.

Here are the exact concepts you must memorise:

- Subsearch default result limit: 50,000 events.
- Subsearch time range inheritance: inherits from outer search.
- Subsearch output: must be a single field list for IN or a single value for = comparisons.
- Append does not filter; it stacks results.
- Append requires the subsearch to be wrapped in square brackets.
- 'appendcols' exists but is a different command (it appends columns, not rows).

Exam traps to watch for:

- The 'report' command in a subsearch is not the same as 'search'. They may test if you know that 'search' is the implied command.
- They might give a subsearch that returns no results. The outer search then returns zero results, not an error.
- They might present a scenario where the subsearch uses 'stats' and the outer search uses 'stats' with different field names. The result could be empty.
- They might test that append can only be used once in a query, which is false; you can chain multiple appends.

Finally, practical lab-style questions on the exam might show a snippet of a search and ask: 'What will the output look like?' You need to mentally simulate the subsearch execution order. Always remember: subsearch runs first, then the outer search uses its output. Append runs its subsearch after the main search finishes, then stacks the results.

Focus on these three skills:

- Write a subsearch to filter events by a list from another source.
- Write an append to compare two time periods.
- Debug why a subsearch returns no results (often due to time range or field name mismatch).

Practise with the free Splunk sandbox. The exam expects you to be comfortable with these commands, not just theoretically but in practice.

## Step by step

1. **Identify your goal** — Decide whether you need to filter results (use subsearch) or combine separate results (use append). This determines which command to start with.
2. **Write the outer (main) search** — Start with the search that will produce the final result set you care about. For a subsearch, this is the larger search that will be filtered. For an append, this is the first set of results you want to see.
3. **Write the inner search (subsearch or appended query)** — For a subsearch, enclose the inner search in square brackets [ ] and ensure it produces a single field (e.g., using 'fields user'). For an append, place the second search inside brackets after 'append [' and ensure it outputs matching field names.
4. **Set the time range** — If your inner search needs a different time window than the outer search, add an explicit time range inside the brackets (e.g., earliest=-24h@h latest=@h). Otherwise, both searches share the same time range.
5. **Run and validate the query** — Execute the search and check the results. For a subsearch, verify that only matching events appear. For an append, confirm that both sets of rows are present and that field names align correctly.

## Comparisons

### Subsearch vs Append

**Subsearch:**
- Runs the inner search first, then uses its output to filter the outer search.
- Returns a single result set that is a subset of the outer search's data.
- The subsearch output must be a single field value used in a filter (e.g., IN or =).

**Append:**
- Runs the main search, then runs a second search independently and stacks the results.
- Returns two result sets combined vertically into one table.
- The second search can produce any fields; they are simply added as new rows.

### Subsearch vs Join

**Subsearch:**
- Filters the outer search using values from the inner search.
- Does not require matching field names; the outer search uses the value list.
- Typically returns fewer results than a join because it is a filter.

**Join:**
- Combines two datasets based on a common field (like a SQL join).
- Requires the field to exist in both datasets with the same name.
- Can return all results from both sides, including non-matches depending on join type.

### Append vs Appendcols

**Append:**
- Adds new rows from the second search below the first search's rows.
- Useful for comparing time periods or aggregations.
- Field name mismatch leads to empty columns in the stacked table.

**Appendcols:**
- Adds new columns from the second search to the right of the first search's columns.
- Useful for side-by-side comparison of different metrics.
- Field name mismatch can cause misalignment or empty cells.

## Diagram

_This flowchart shows the two distinct paths: subsearch filters the outer search, while append stacks independent results._

```mermaid
flowchart TD
    A[Outer Search] --> B{Which command?}
    B -->|Subsearch| C[Subsearch inside brackets]
    C --> D[Subsearch runs first]
    D --> E[Produces list of values]
    E --> F[Outer search filters using that list]
    F --> G[Final filtered results]
    B -->|Append| H[Main search runs first]
    H --> I[Second search inside brackets]
    I --> J[Second search runs independently]
    J --> K[Results stacked vertically]
    K --> L[Final combined results]
```

## Common misconceptions

- **Misconception:** A subsearch and an append do the same thing because they both combine results from multiple searches. **Reality:** A subsearch nests one search inside another to filter results, while an append runs two searches independently and stacks their results. They serve different purposes and are not interchangeable. (New learners see both commands involving two searches and assume they are synonyms. The key difference in filtering versus stacking is subtle until you use them in practice.)
- **Misconception:** If a subsearch returns no results, the outer search will return an error and stop. **Reality:** If a subsearch returns no results, the outer search will simply return zero results. There is no error, because the outer search still executes but finds nothing to match. (Many beginners come from programming where a null result would break a loop. Splunk handles empty subsearches gracefully, which confuses people who expect an error message.)
- **Misconception:** You can use subsearch inside an append to filter both the main search and the appended search. **Reality:** A subsearch inside an append only filters the second search (the one inside the brackets). The main search runs independently without considering the subsearch. (Because the subsearch is placed inside the square brackets of the append argument, learners assume it applies to both parts. The syntax clearly limits it to the appended query.)
- **Misconception:** The subsearch always uses the 'All time' time range unless you explicitly set it. **Reality:** By default, the subsearch inherits the time range of the outer search. You must explicitly set a different time range inside the subsearch if you want to override. (In many other contexts (like scheduled reports), inheritance is not automatic, so beginners assume subsearch also defaults to 'All time'. Splunk's inheritance behaviour is a common exam trap.)
- **Misconception:** You can use subsearch multiple times in one outer search without any limit. **Reality:** You can use multiple subsearches, but each subsearch counts toward the total runtime and result limits. Having many subsearches can slow down your query significantly, and each subsearch has its own 50,000 event limit. (Beginners think 'more subsearches = more power', but performance constraints apply. The exam tests understanding of scalability, not just syntax.)

## Key takeaways

- A subsearch runs first, inside square brackets, and its output filters the outer search's results.
- An append runs a second search after the first and stacks the results vertically into one table.
- The default maximum number of events a subsearch can return is 50,000; any extra events are ignored.
- A subsearch inherits the time range of the outer search unless you specify a different one inside the subsearch.
- If a subsearch returns no results, the outer search still executes but simply returns zero results.
- Use subsearch when you need to filter one dataset based on values from another, and use append when you want to compare separate datasets side by side.

## FAQ

**Can I use a subsearch without the 'fields' command?**

Yes, but it is strongly recommended to use 'fields' to limit the output to only the field you need. If you omit it, the subsearch returns all fields, which can cause the outer search to fail or match incorrectly.

**What happens if my subsearch returns more than 50,000 results?**

Splunk truncates the subsearch results to 50,000 events by default. Any events beyond that are ignored, which might cause your outer search to miss important matches.

**Does append replace the results of the first search?**

No, append adds the results of the second search below the first set of results. Both sets remain intact; it is a stacking, not a replacement.

**Can I use multiple appends in one query?**

Yes, you can chain multiple appends one after another. Each append runs its own subsearch and stacks the results sequentially.

**Why does my subsearch return no results even though the data exists?**

The most common reasons are a mismatched time range (the subsearch inherits the outer search's time window) or a field name typo in the 'fields' command. Check your time range and field names.

**Is 'appendcols' the same as 'append'?**

No. Append stacks rows (results), while appendcols stacks columns (side by side). They are different commands for different purposes.

## Check your understanding

1. **What is the default maximum number of events a subsearch can return?**

   Answer: 50,000 events.

2. **If you do not specify a time range inside a subsearch, what time range does it use?**

   Answer: It inherits the time range of the outer search.

3. **Which command would you use to filter login events to only include users who appear in a list of suspicious users from a different lookup?**

   Answer: A subsearch (using square brackets with the inner search that produces the list of users).

4. **What happens to the outer search if the subsearch returns no results?**

   Answer: The outer search returns zero results; it does not produce an error.

5. **What is the key difference between 'append' and 'appendcols'?**

   Answer: Append stacks results as new rows, while appendcols adds results as new columns to the right.

---

Interactive version with quiz and diagrams: https://courseiva.com/learn/splunk-core-certified-power-user/search-commands-subsearch-and-append