Rewrite conversion functions #498
Conversation
gordallott
left a comment
gordallott
left a comment
There was a problem hiding this comment.
got a few changes to do here and just a bunch of notes about conversions that you might or might not want to document
|
|
||
| ```kusto | ||
| ['otel-demo-traces'] | ||
| | extend is_success = tobool(toint(['status_code']) < 400) |
There was a problem hiding this comment.
this is pretty silly, toint(['status_code']) < 400 is already a bool, same with the line below this. the logic for tobool(<value>) is first, if it's already a bool, then nothing is changed
- if value is an integer/float/duration: returns true if value != 0
- if value is a datetime: returns true if the value is anything other than epoch
- if value is a string: returns true if value equals "1", "t", "T", "TRUE", "true", "True", false if the value is: "0", "f", "F", "FALSE", "false", "False". or a nil if it's any other string
so tests that just tobool() a conditional don't make much sense, this function is a type conversion so tests about that instead
|
|
||
| Use the `todouble` function (or its synonym `toreal`) to convert various data types to a real (floating-point) number. This is helpful when you need to normalize numeric values from different sources into decimal format for mathematical operations, comparisons, or aggregations. | ||
|
|
||
| You typically use `todouble` when working with numeric strings, integers, or other types that need to be converted to floating-point numbers for precise calculations or when decimal precision is required. |
There was a problem hiding this comment.
some specifics about the conversions here that might be helpful:
- integers are just converted to floats simply (1 = 1.0, -1=1.0)
- strings are parsed as a 64-bit float, using the go-syntax for floating point literals, so that means you can use for example, e numbers https://play.axiom.co/axiom-play-qf1k/query?qid=zGW7fQwqil9-t75lzq&relative=1
- for bools, true=1.0, false=0.0
- datetime's are converted to nanoseconds since epoch
- durations are converted to float nanosecond's
| Use the `todatetime` function to convert various data types to a datetime value. This is helpful when you need to normalize date and time values from different formats or sources into a standard datetime format for comparison, filtering, or time-based analysis. | ||
|
|
||
| You typically use `todatetime` when working with date strings, timestamps, or other time representations that need to be converted to datetime format for time-based operations. |
There was a problem hiding this comment.
more specifics about the conversions that may be helpful
- integers/floats are assumed to be nanoseconds since epoch
- strings are parsed with the
dateparsepackage, which accepts a lot of formats, which isn't super helpful. but there's a list of examples in the upstream repo that might be: https://raw.githubusercontent.com/araddon/dateparse/master/example/main.go
| | extend duration_ns = req_duration_ms * 1000 | ||
| | extend duration_num = tolong(duration_ns) | | ||
| | extend hex_duration = tohex(duration_num, 8) |
There was a problem hiding this comment.
not a great example, whos going to want a hex duration? more obvious examples would be things like numeric ID's that might be more readable as hex, so if there was a field called id that was just a random integer number. then you might extend idStr = tohex(id) or something
| description: 'This page explains how to use the toint function in APL.' | ||
| --- | ||
|
|
||
| Use the `toint` function to convert various data types to an integer (signed 64-bit) value. This is helpful when you need to normalize numeric values from different sources into integer format for mathematical operations, comparisons, or when decimal precision isn’t required. |
There was a problem hiding this comment.
notes on conversion specifics for this one is basically the same as todouble(), but obviously to integers
the big difference is strings expect a more strict subset, basically just "+<integer>" and "-<integer>" nothing fancy like hex values. I might change this so that it can parse hex values and such, but today it doesn't and i'll let you know if that changes
| --- | ||
| title: tolong | ||
| description: 'This page explains how to use the tolong function in APL.' | ||
| --- | ||
|
|
||
| Use the `tolong` function to convert various data types to a long (signed 64-bit) integer value. This is helpful when you need to normalize numeric values from different sources into long integer format for mathematical operations, comparisons, or when working with large numeric identifiers. | ||
|
|
||
| You typically use `tolong` when working with numeric strings, floating-point numbers, or other types that need to be converted to long integers, especially when dealing with large numbers that exceed the standard integer range. |
There was a problem hiding this comment.
toint/tolong are the exact same, there is no distinction between them in bitdepth. I don't think we should document both independently, its like todouble/toreal
|
|
||
| Use the `tostring` function to convert various data types to a string representation. This is helpful when you need to normalize values from different sources into string format for string operations, concatenation, or display purposes. | ||
|
|
||
| You typically use `tostring` when working with numeric values, booleans, or other types that need to be converted to strings for string manipulation, formatting, or when combining values in string operations. |
There was a problem hiding this comment.
more conversion specifics:
- ints are formatted as base-10
- floats are formatted as defined by the g string here: https://pkg.go.dev/strconv#FormatFloat with -1 for precision (this is likely too much details for docs, but just noting it)
- bools return as "true"/"false", and nil bools return "false"
- durations return duration formatted strings like 1m20s
- datetimes return an RFC3339Nano formatted datetime
| Use the `totimespan` function to convert various data types to a timespan value representing a duration. This is helpful when you need to normalize duration values from different sources into timespan format for time-based calculations, comparisons, or aggregations. | ||
|
|
||
| You typically use `totimespan` when working with duration strings, numeric values representing time intervals, or other types that need to be converted to timespan format for duration calculations. |
There was a problem hiding this comment.
conversion notables:
- integers/floats are converted as nanoseconds, so 1000000000 for one second
- strings are converted via duration strings, ref:
// A duration string is a possibly signed sequence of
// decimal numbers, each with optional fraction and a unit suffix,
// such as "300ms", "-1.5h" or "2h45m".
// Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".
|
|
||
| ```kusto APL equivalent | ||
| ['sample-http-logs'] | ||
| | extend duration = totimespan('1.00:00:00') |
There was a problem hiding this comment.
no, duration strings are required not this
There was a problem hiding this comment.
same as other uses of non duration strings below
…docs into mano/conversion-rewrite
|
@gordallott Many thanks for this. I've implemented your reviews in a single commit for easier comparison: 7408d31 I've rewritten the forced examples so that they don't link to the Playground anymore but at least they make more sense. |
2 participants
Previews:
Old docs used to miss second, optional param of
tohex.To compare old and new docs more easily: https://github.com/axiomhq/docs/pull/502/files