Improve onboarding pages for ingesting and querying (#258)

Author: tothmano

apl/entities/entity-names.mdx

@@ -36,6 +36,6 @@ Quote an identifier in your APL query if any of the following is true:
     - Dash (`-`)
 - The identifier name is identical to one of the reserved keywords of the APL query language. For example, `project` or `where`.
 
-If any of the above is true, you must quote the identifier by putting it in quotation marks (`'` or `"`) and square brackets (`[]`). For example, `['my-field']`.
+If any of the above is true, you must quote the identifier by enclosing it in quotation marks (`'` or `"`) and square brackets (`[]`). For example, `['my-field']`.
 
 If none of the above is true, you don’t need to quote the identifier in your APL query. For example, `myfield`. In this case, quoting the identifier name is optional.

apl/introduction.mdx

@@ -6,45 +6,92 @@ icon: door-open
 tags: ['axiom documentation', 'documentation', 'axiom', 'APL', 'axiom processing language', 'data explorer', 'getiing started guide', 'summarize', 'filter']
 ---
 
-## Introduction
+import Prerequisites from "/snippets/minimal-prerequisites.mdx"
 
 The Axiom Processing Language (APL) is a query language that is perfect for getting deeper insights from your data. Whether logs, events, analytics, or similar, APL provides the flexibility to filter, manipulate, and summarize your data exactly the way you need it.
 
-## Get started
+<Prerequisites />
 
-Go to the Query tab and click one of your datasets to get started. The APL editor has full auto-completion so you can poke around or you can get a better understanding of all the features by using the reference menu to the left of this page.
+## Build an APL query
 
-## APL query structure
+APL queries consist of the following:
 
-At a minimum, a query consists of source data reference (name of a dataset) and zero or more query operators applied in sequence. Individual operators are delimited using the pipe character (`|`).
+- **Data source:** The most common data source is one of your Axiom datasets.
+- **Operators:** Operators filter, manipulate, and summarize your data. 
 
-APL query has the following structure:
+Delimit operators with the pipe character (`|`).
+
+A typical APL query has the following structure:
 
 ```kusto
-DataSource
-| operator ...
-| operator ...
+DatasetName
+| Operator ...
+| Operator ...
 ```
 
-Where:
+- `DatasetName` is the name of the dataset you want to query.
+- `Operator` is an operation you apply to the data.
 
-- DataSource is the name of the dataset you want to query
-- Operator is a function that will be applied to the data
+<Note>
+Apart from Axiom datasets, you can use other data sources:
+- External data sources using the [externaldata](/apl/tabular-operators/externaldata-operator) operator.
+- Specify a data table in the APL query itself using the `let` statement.
+</Note>
 
-Let’s look at an example query.
+## Example query
 
 ```kusto
 ['github-issue-comment-event']
-| extend bot = actor contains "-bot" or actor contains "[bot]"
-| where bot == true
+| extend isBot = actor contains '-bot' or actor contains '[bot]'
+| where isBot == true
 | summarize count() by bin_auto(_time), actor
 ```
 
-The query above begins with reference to a dataset called **github-issue-comment-event** and contains several operators, [extend](/apl/tabular-operators/extend-operator), [where](/apl/tabular-operators/where-operator), and [summarize](/apl/tabular-operators/summarize-operator), each separated by a `pipe`. The extend operator creates the **bot** column in the returned result, and sets its values depending on the value of the actor column, the **where** operator filters out the value of the **bot** to a branch of rows and then produce a chart from the aggregation using the **summarize** operator.
+[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B'github-issue-comment-event'%5D%20%7C%20extend%20isBot%20%3D%20actor%20contains%20'-bot'%20or%20actor%20contains%20'%5Bbot%5D'%20%7C%20where%20isBot%20%3D%3D%20true%20%7C%20summarize%20count()%20by%20bin_auto(_time)%2C%20actor%22%7D)
+
+The query above uses a dataset called `github-issue-comment-event` as its data source. It uses the follwing operators:
+
+- [extend](/apl/tabular-operators/extend-operator) adds a new field `isBot` to the query results. It sets the values of the new field to true if the values of the `actor` field in the original dataset contain `-bot` or `[bot]`.
+- [where](/apl/tabular-operators/where-operator) filters for the values of the `isBot` field. It only returns rows where the value is true.
+- [summarize](/apl/tabular-operators/summarize-operator) aggregates the data and produces a chart.
+
+Each operator is separated using the pipe character (`|`).
+
+## Example result
+
+As a result, the query returns a chart and a table. The table counts the different values of the `actor` field where `isBot` is true, and the chart displays the distribution of these counts over time.
+
+| actor               | count_ |
+|---------------------|--------|
+| github-actions[bot] |    487 |
+| sonarqubecloud[bot] |    208 |
+|   dependabot[bot]   |    148 |
+|     vercel[bot]     |     91 |
+|     codecov[bot]    |     63 |
+|  openshift-ci[bot]  |     52 |
+|  coderabbitai[bot]  |     43 |
+|     netlify[bot]    |     37 |
+
+<Note>
+The query results are a representation of your data based on your request. The query doesn’t change the original dataset.
+</Note>
+
+## Quote dataset and field names
+
+If the name of a dataset or field contains at least one of the following special characters, quote the name in your APL query:
+    - Space (` `)
+    - Dot (`.`)
+    - Dash (`-`)
+
+To quote the dataset or field in your APL query, enclose its name with quotation marks (`'` or `"`) and square brackets (`[]`). For example, `['my-field']`.
+
+For more information on rules about naming and quoting entities, see [Entity names](/apl/entities/entity-names).
 
-The most common kind of query statement is a tabular expression statement. Tabular statements contain operators, each of which starts with a tabular `input` and returns a tabular `output.`
+## What's next
 
-- Explore the [tabular operators](/apl/tabular-operators/extend-operator) we support.
-- Check out our [entity names and identifier naming rules](/apl/entities/entity-names).
+Check out the [list of sample queries](/apl/tutorial) or explore the supported operators and functions:
 
-Axiom Processing Language supplies a set of system [data types](/apl/data-types/scalar-data-types) that define all the types of [data](/apl/data-types/null-values) that can be used with Axiom Processing Language.
+- [Scalar functions](/apl/scalar-functions/)
+- [Aggregation functions](/apl/aggregation-function/)
+- [Tabular operators](/apl/tabular-operators/)
+- [Scalar operators](/apl/scalar-operators/)