forked from Azure/azure-kusto-go
-
Notifications
You must be signed in to change notification settings - Fork 0
/
doc.go
173 lines (138 loc) · 6.43 KB
/
doc.go
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
// Copyright 2020 Microsoft Corporation. All rights reserved.
// Use of this source code is governed by an MIT
// license that can be found in the LICENSE file.
//
// Additional licenses for third-pary packages can be found in third_party_licenses/
/*
Package kusto provides a client for accessing Azure Data Explorer, also known as Kusto.
For details on the Azure Kusto service, see: https://azure.microsoft.com/en-us/services/data-explorer/
For general documentation on APIs and the Kusto query language, see: https://docs.microsoft.com/en-us/azure/data-explorer/
# Creating an Authorizer and a Client
To begin using this package, create an Authorizer and a client targeting your Kusto endpoint:
// auth package is: "github.com/Azure/go-autorest/autorest/azure/auth"
authorizer := kusto.Authorization{
Config: auth.NewClientCredentialsConfig(clientID, clientSecret, tenantID),
}
client, err := kusto.New(endpoint, authorizer)
if err != nil {
panic("add error handling")
}
For more examples on ways to create an Authorization object, see the Authorization object documentation.
# Querying for Rows
Kusto provides a single method for querying, Query(). Query uses a Stmt object to provides SQL-like injection protection
and accepts only string constants for arguments.
// table package is: data/table
// Query our database table "systemNodes" for the CollectionTimes and the NodeIds.
iter, err := client.Query(ctx, "database", kusto.NewStmt("systemNodes | project CollectionTime, NodeId"))
if err != nil {
panic("add error handling")
}
defer iter.Stop()
// .Do() will call the function for every row in the table.
err = iter.Do(
func(row *table.Row) error {
if row.Replace {
fmt.Println("---") // Replace flag indicates that the query result should be cleared and replaced with this row
}
fmt.Println(row) // As a convenience, printing a *table.Row will output csv
return nil
},
)
if err != nil {
panic("add error handling")
}
# Querying Rows Into Structs
Keeping our query the same, instead of printing the Rows we will simply put them into a slice of structs
// NodeRec represents our Kusto data that will be returned.
type NodeRec struct {
// ID is the table's NodeId. We use the field tag here to to instruct our client to convert NodeId to ID.
ID int64 `kusto:"NodeId"`
// CollectionTime is Go representation of the Kusto datetime type.
CollectionTime time.Time
}
iter, err := client.Query(ctx, "database", kusto.NewStmt("systemNodes | project CollectionTime, NodeId"))
if err != nil {
panic("add error handling")
}
defer iter.Stop()
recs := []NodeRec{}
err = iter.Do(
func(row *table.Row) error {
rec := NodeRec{}
if err := row.ToStruct(&rec); err != nil {
return err
}
if row.Replace {
recs = recs[:0] // Replace flag indicates that the query result should be cleared and replaced with this row
}
recs = append(recs, rec)
return nil
},
)
if err != nil {
panic("add error handling")
}
A struct object can use fields to store the Kusto values as normal Go values, pointers to Go values and as value.Kusto types.
The value.Kusto types are useful when you need to distiguish between the zero value of a variable and the value not being
set in Kusto.
All value.Kusto types have a .Value and .Valid field. .Value is the native Go value, .Valid is a bool which
indicates if the value was set. More information can be found in the sub-package data/value.
The following is a conversion table from the Kusto column types to native Go values within a struct that are allowed:
From Kusto Type To Go Kusto Type
==============================================================================
bool value.Bool, bool, *bool
------------------------------------------------------------------------------
datetime value.DateTime, time.Time, *time.Time
------------------------------------------------------------------------------
dynamic value.Dynamic, string, *string
------------------------------------------------------------------------------
guid value.GUID, uuid.UUID, *uuid.UUID
------------------------------------------------------------------------------
int value.Int, int32, *int32
------------------------------------------------------------------------------
long value.Long, int64, *int64
------------------------------------------------------------------------------
real value.Real, float64, *float64
------------------------------------------------------------------------------
string value.String, string, *string
------------------------------------------------------------------------------
timestamp value.Timestamp, time.Duration, *time.Duration
------------------------------------------------------------------------------
decimal value.Decimal, string, *string
==============================================================================
For more information on Kusto scalar types, see: https://docs.microsoft.com/en-us/azure/kusto/query/scalar-data-types/
# Stmt
Every query is done using a Stmt. A Stmt is built with Go string constants and can do variable substitution
using Kusto's Query Paramaters.
// rootStmt builds a query that will gather all nodes in the DB.
rootStmt := kusto.NewStmt("systemNodes | project CollectionTime, NodeId")
// singleNodeStmt creates a new Stmt based on rootStmt and adds a "where" clause to find a single node.
// We pass a definition that sets the word ParamNodeId to a variable that will be substituted for a
// Kusto Long type (which is a a Go int64).
singleNodeStmt := rootStmt.Add(" | where NodeId == ParamNodeId").MustDefinitions(
kusto.NewDefinitions().Must(
kusto.ParamTypes{
"ParamNodeId": kusto.ParamType{Type: types.Long},
},
),
)
// Query using our singleNodeStmt, variable substituting for ParamNodeId
iter, err := client.Query(
ctx,
"database",
singleNode.MustParameters(
kusto.NewParameters().Must(
kusto.QueryValues{"ParamNodeId": int64(100)},
),
),
)
# Ingest
Support for Kusto ingestion from local files, Azure Blob Storage and streaming is supported in the sub-package ingest.
See documentation in that package for more details
# Mocking
To support mocking for this client in your code for hermetic testing purposes, this client supports mocking the data
returned by our RowIterator object. Please see the MockRows documentation for code examples.
# Package Examples
Below you will find a simple and complex example of doing Query() the represent compiled code:
*/
package kusto