Merge pull request #6595 from MicrosoftDocs/main

Publish to live, Wednesday 4AM PST, 1/29

Author: PMEds28

.github/pull_request_template.md

@@ -4,10 +4,10 @@ Please add a brief comment outlining the purpose of this PR. Add links to any re
 
 ## Make sure you've done the following:
 
-1. **Acrolinx:** Make sure your Acrolinx score is **at least 80** (higher is better) and with **0** spelling issues.
+1. **Acrolinx**: Make sure your Acrolinx score is **at least 80** (higher is better) and with **0** spelling issues.
 1. **Successful build**: Review the build status to make sure **all files are green** (Succeeded) and there are no errors, warnings, or suggestions.
 1. **Preview the pages**: Click each **Preview URL** link, scan the entire page looking for formatting issues, in particular the parts you edited.
-1. **Check the Table of Contents:** If you're adding a new markdown file, make sure it is linked from the table of contents.
+1. **Check the Table of Contents**: If you're adding a new markdown file, make sure it is linked from the table of contents.
 1. **Sign off**: Once the PR is finalized, add a comment with `#sign-off` . If you need to cancel the sign-off, add a comment with `#hold-off`.
 
     **NOTE**: *Signing off means the document can be published at any time.*

data-explorer/kusto/includes/help-cluster-samples-stormevents.md

@@ -3,7 +3,7 @@ title: .create function command
 description: Learn how to use the `.create function` command to create a stored function.
 ms.reviewer: orspodek
 ms.topic: reference
-ms.date: 08/11/2024
+ms.date: 12/19/2024
 ---
 # .create function command
 
@@ -71,7 +71,7 @@ You must have at least [Database User](../access-control/role-based-access-contr
 
 ## Examples
 
-### Simple demo function
+### Simple function
 
 The following example creates the `MyFunction1` function with a description (`docstring`), a folder named `Demo`, and defines the function.
 
@@ -86,17 +86,18 @@ MyFunction1()
 |---|---|---|---|---|
 |MyFunction1|()|{StormEvents | take 100}|Demo|Simple demo function|
 
-### Demo function with parameter
+### Function with a parameter
 
-The following example creates the *MyFunction2* function with a description (`docstring`), folder named `Demo`, and defines the `MyLimit` parameter.
+The following example creates the `MyFunction2` function with a description (`docstring`), folder named `Demo`, and defines the `Mytimestamp` parameter.
 
 ```kusto
-.create function
-with (docstring = 'Demo function with parameter', folder='Demo')
- MyFunction2(myLimit: long)
-{StormEvents | take myLimit}
+.create function with (docstring = "Demo function with date parameter",folder = "Demo") 
+ MyFunction2(Mytimestamp:datetime) {
+    StormEvents
+    | where EndTime <= Mytimestamp
+ }
 ```
 
 |Name|Parameters|Body|Folder|DocString|
 |---|---|---|---|---|
-|MyFunction2|(myLimit:long)|{StormEvents &#124; take myLimit}|Demo|Demo function with parameter|
+|MyFunction2|(Mytimestamp:datetime)|{StormEvents &#124; where EndTime <= Mytimestamp}|Demo|Demo function with date parameter|

data-explorer/kusto/management/create-function.md

@@ -9,7 +9,7 @@ ms.date: 12/08/2024
 
 > [!INCLUDE [applies](../../includes/applies-to-version/applies.md)] [!INCLUDE [fabric](../../includes/applies-to-version/fabric.md)] [!INCLUDE [azure-data-explorer](../../includes/applies-to-version/azure-data-explorer.md)]
 
-Returns all failures logged as part of the continuous export. To view only a specific time range, filter the results by the **Timestamp** column.
+Returns all failures logged as part of the continuous export within the past 14 days. To view only a specific time range, filter the results by the **Timestamp** column.
 
 ::: moniker range="azure-data-explorer"
 The command doesn't return any results if executed on a [follower database](/azure/data-explorer/follower), it must be executed against the leader database.

data-explorer/kusto/management/data-export/show-continuous-failures.md

@@ -14,7 +14,7 @@ Ingestion mappings are used during ingestion to map incoming data to columns ins
 
 Data Explorer supports different types of mappings, both row-oriented (CSV, JSON, AVRO and W3CLOGFILE), and column-oriented (Parquet and ORC).
 
-Ingestion mappings can be [precreated](create-ingestion-mapping-command.md) and can be referenced from the ingest command using `ingestionMappingReference` parameters. Ingestion is possible without specifying a mapping. For more information, see [identity mapping](#identity-mapping).
+Ingestion mappings can be defined in the ingest command, or can be [precreated](create-ingestion-mapping-command.md) and referenced from the ingest command using `ingestionMappingReference` parameters. Ingestion is possible without specifying a mapping. For more information, see [identity mapping](#identity-mapping).
 
 Each element in the mapping list is constructed from three fields:
 
@@ -47,6 +47,63 @@ The following table defines mapping types to be used when ingesting or querying
 | ORC         | [ORC Mapping](orc-mapping.md)                 |
 | W3CLOGFILE  | [W3CLOGFILE Mapping](w3c-log-file-mapping.md) |
 
+
+## Ingestion mapping examples
+
+The following examples use the `RawEvents` table with the following schema:
+
+```kusto
+.create table RawEvents (timestamp: datetime, deviceId: guid, messageId: guid, temperature: decimal, humidity: decimal) 
+```
+
+### Simple mapping
+
+The following example shows ingestion where the mapping is defined in the ingest command. The command ingests a JSON file from a URL into the `RawEvents` table. The mapping specifies the path to each field in the JSON file.
+
+````kusto
+.ingest into table RawEvents ('https://kustosamplefiles.blob.core.windows.net/jsonsamplefiles/simple.json') 
+    with (
+            format = "json",
+            ingestionMapping =
+            ```
+            [ 
+              {"column":"timestamp","Properties":{"path":"$.timestamp"}},
+              {"column":"deviceId","Properties":{"path":"$.deviceId"}},
+              {"column":"messageId","Properties":{"path":"$.messageId"}},
+              {"column":"temperature","Properties":{"path":"$.temperature"}},
+              {"column":"humidity","Properties":{"path":"$.humidity"}}
+            ]
+            ```
+          )
+````
+
+### Mapping with `ingestionMappingReference`
+
+To map the same JSON file using a precreated mapping, create the `RawEventMapping` ingestion mapping reference with the following command:
+
+````kusto
+.create table RawEvents ingestion json mapping 'RawEventMapping' 
+  ```
+  [ 
+    {"column":"timestamp","Properties":{"path":"$.timestamp"}},
+    {"column":"deviceId","Properties":{"path":"$.deviceId"}},
+    {"column":"messageId","Properties":{"path":"$.messageId"}},
+    {"column":"temperature","Properties":{"path":"$.temperature"}},
+    {"column":"humidity","Properties":{"path":"$.humidity"}}
+  ]
+  ```
+````
+
+Ingest the JSON file using the `RawEventMapping` ingestion mapping reference with the following command:
+
+```kusto
+.ingest into table RawEvents ('https://kustosamplefiles.blob.core.windows.net/jsonsamplefiles/simple.json') 
+  with (
+          format="json",
+          ingestionMappingReference="RawEventMapping"
+        )
+```
+
 ## Identity mapping
 
 Ingestion is possible without specifying `ingestionMapping` or `ingestionMappingReference` properties. The data is mapped using an identity data mapping derived from the table's schema. The table schema remains the same. `format` property should be specified. See [ingestion formats](../ingestion-supported-formats.md).

data-explorer/kusto/management/mappings.md

@@ -65,7 +65,7 @@ A request rate limit of kind `ResourceUtilization` includes the following proper
 |--|--|--|--|
 | ResourceKind | `ResourceKind` | The resource to limit.</br></br>When `ResourceKind` is `TotalCpuSeconds`, the limit is enforced based on post-execution reports of CPU utilization of completed requests. Requests that report utilization of 0.005 seconds of CPU or lower aren't counted. The limit (`MaxUtilization`) represents the total CPU seconds that can be consumed by requests within a specified time window (`TimeWindow`). For example, a user running ad-hoc queries may have a limit of 1000 CPU seconds per hour. If this limit is exceeded, subsequent queries will be throttled, even if started concurrently, as the cumulative CPU seconds have surpassed the defined limit within the sliding window period. | `RequestCount`, `TotalCpuSeconds` |
 | MaxUtilization | `long` | The maximum of the resource that can be utilized. | RequestCount: [`1`, `16777215`]; TotalCpuSeconds: [`1`, `828000`] |
-| TimeWindow | `timespan` | The sliding time window during which the limit is applied. | [`00:01:00`, `1.00:00:00`] |
+| TimeWindow | `timespan` | The sliding time window during which the limit is applied. | [`00:00:01`, `01:00:00`] |
 
 When a request exceeds the limit on resources utilization:
 

data-explorer/kusto/management/request-rate-limit-policy.md

@@ -16,16 +16,16 @@ The `graph-match` operator searches for all occurrences of a graph pattern in an
 
 ## Syntax
 
-*G* `|` `graph-match` [`cycles` `=` *CyclesOption*]  *Pattern* `where` *Constraints* `project` [*ColumnName* `=`] *Expression* [`,` ...]
+*G* `|` `graph-match` [`cycles` `=` *CyclesOption*]  *Pattern* [`where` *Constraints*] `project` [*ColumnName* `=`] *Expression* [`,` ...]
 
 ## Parameters
 
 | Name | Type | Required | Description |
 |--|--|--|--|
 | *G* | `string` |  :heavy_check_mark: | The input graph source. |
 | *Pattern* | `string` |  :heavy_check_mark: | One or more comma delimited sequences of graph node elements connected by graph edge elements using graph notations. See [Graph pattern notation](#graph-pattern-notation). |
-| *Constraints* | `string` |  :heavy_check_mark: | A Boolean expression composed of properties of named variables in the *Pattern*. Each graph element (node/edge) has a set of properties that were attached to it during the graph construction. The constraints define which elements (nodes and edges) are matched by the pattern. A property is referenced by the variable name followed by a dot (`.`) and the property name. |
-| *Expression* | `string` |  | The `project` clause converts each pattern to a row in a tabular result. The project expression(s) have to be scalar and reference properties of named variables defined in the *Pattern*. A property is referenced by the variable name followed by a dot (`.`) and the attribute name. |
+| *Constraints* | `string` |  | A Boolean expression composed of properties of named variables in the *Pattern*. Each graph element (node/edge) has a set of properties that were attached to it during the graph construction. The constraints define which elements (nodes and edges) are matched by the pattern. A property is referenced by the variable name followed by a dot (`.`) and the property name. |
+| *Expression* | `string` | :heavy_check_mark: | The `project` clause converts each pattern to a row in a tabular result. The project expression(s) have to be scalar and reference properties of named variables defined in the *Pattern*. A property is referenced by the variable name followed by a dot (`.`) and the attribute name. |
 | *CyclesOption* | `string` |  | Controls whether cycles are matched in the *Pattern*, allowed values: `all`, `none`, `unique_edges`. If `all` is specified then all cycles are matched, if `none` is specified cycles aren't matched, if `unique_edges` (default) is specified, cycles are matched but only if the cycles don't include the same edge more than once. |
 
 

data-explorer/kusto/query/graph-match-operator.md

@@ -3,7 +3,7 @@ title:  invoke operator
 description: Learn how to use the  invoke operator to invoke a lambda expression that receives the source of `invoke` as a tabular parameter argument
 ms.reviewer: alexans
 ms.topic: reference
-ms.date: 08/11/2024
+ms.date: 01/15/2025
 ---
 # invoke operator
 
@@ -34,7 +34,7 @@ Returns the result of the evaluated expression.
 
 ## Example
 
-The following example shows how to use the `invoke` operator to call lambda `let` expression:
+This example shows how to use the `invoke` operator to call lambda `let` expression:
 
 :::moniker range="azure-data-explorer"
 > [!div class="nextstepaction"]

data-explorer/kusto/query/invoke-operator.md

@@ -3,7 +3,7 @@ title:  Cross-cluster join
 description: Learn how to perform the Cross-cluster join operation to join datasets residing on different clusters.
 ms.reviewer: alexans
 ms.topic: reference
-ms.date: 08/11/2024
+ms.date: 01/26/2025
 monikerRange: "microsoft-fabric || azure-data-explorer"
 ---
 # Cross-cluster join
@@ -57,40 +57,31 @@ The following list explains the supported values for the *Strategy* parameter:
 
 ## How the auto strategy works
 
-By default, the `auto` strategy determines where the cross-cluster join should be executed based on the following rules:
+By default, the `auto` strategy determines where the cross-cluster join is executed based on the following rules:
 
-* If one of the tables is hosted in the local cluster, then the join is performed on the local cluster.
-* If both tables are hosted outside of the local cluster, then join is performed on the right cluster.
+* If one of the tables is hosted in the local cluster, then the join is performed on the local cluster. For example, with the auto strategy, this query is executed on the local cluster:
 
-Consider the following examples:
+    ```kusto
+    T | ... | join (cluster("B").database("DB").T2 | ...) on Col1
+    ```
 
-```kusto
-// Example 1
-T | ... | join (cluster("B").database("DB").T2 | ...) on Col1
-
-// Example 2
-cluster("B").database("DB").T | ... | join (cluster("C").database("DB2").T2 | ...) on Col1
-```
+* If both tables are hosted outside of the local cluster, then join is performed on the right cluster. For example, assuming neither cluster is the local cluster, the join would be executed on the right cluster:
 
-With the `auto` strategy, "Example 1" would be executed on the local cluster. In "Example 2", assuming neither cluster is the local cluster, the join would be executed on the right cluster.
+    ```kusto
+    cluster("B").database("DB").T | ... | join (cluster("C").database("DB2").T2 | ...) on Col1
+    ```
 
 ## Performance considerations
 
 For optimal performance, we recommend running the query on the cluster that contains the largest table.
 
-Let's consider the following examples again:
+In the following example, if the dataset produced by `T | ...` is smaller than one produced by `cluster("B").database("DB").T2 | ...` then it would be more efficient to execute the join operation on cluster `B`, in this case the right cluster instead of on the local cluster.
 
 ```kusto
-// Example 1
 T | ... | join (cluster("B").database("DB").T2 | ...) on Col1
-
-// Example 2
-cluster("B").database("DB").T | ... | join (cluster("C").database("DB2").T2 | ...) on Col1
 ```
 
-"Example 1" is set to run on the local cluster, but if the dataset produced by `T | ...` is smaller than one produced by `cluster("B").database("DB").T2 | ...` then it would be more efficient to execute the join operation on cluster `B`, in this case the right cluster, instead of on the local cluster.
-
-The following query does this by using the `right` strategy. With the `right` strategy, the join operation is performed on the right cluster, even if left table is in the local cluster.
+You can rewrite the query to use `hint.remote=right` to optimize the performance. In this way, the join operation is performed on the right cluster, even if left table is in the local cluster.
 
 ```kusto
 T | ... | join hint.remote=right (cluster("B").database("DB").T2 | ...) on Col1

data-explorer/kusto/query/join-cross-cluster.md

@@ -31,6 +31,8 @@ A `fullouter` join combines the effect of applying both left and right outer-joi
 
 ## Example
 
+This example query combines rows from both tables X and Y, filling in missing values with NULL where there's no match in the other table. This allows you to see all possible combinations of keys from both tables.
+
 :::moniker range="azure-data-explorer"
 > [!div class="nextstepaction"]
 > <a href="https://dataexplorer.azure.com/clusters/help/databases/Samples?query=H4sIAAAAAAAAA8tJLVGIULBVSEksAcKknFQN79RKq%2BKSosy8dB2FsMSc0lRDq5z8vHRNrmguBSBQT1TXMdSBMJPUdYwQTGMoM1ldx4Qr1porB2h0JH6jjVCNBhpiaIAwxQiJbQxjpwBNNwAZH6FQo5CVn5mnkJ2Zl2KbVpqTk19akloEtDI%2FTwFoEwDuw%2F%2BW2gAAAA%3D%3D" target="_blank">Run the query</a>