< Back
New-MdbcData
Post
NAME New-MdbcData
SYNOPSIS
Creates data documents.
SYNTAX
New-MdbcData [[-InputObject] <PSObject>] [-Convert <ScriptBlock>] [-Id <PSObject>] [-Property <Object[]>] [-NewId]
[<CommonParameters>]
DESCRIPTION
This command is used to create Mdbc.Dictionary documents. Input objects come from the pipeline or as the parameter.
Created documents are used by other module commands. Note that Add-MdbcData and Export-MdbcData also have
parameters Id, NewId, Convert, Property for making documents from input objects, so that in some cases
intermediate use of New-MdbcData is not needed.
Result documents are returned as Mdbc.Dictionary objects. Mdbc.Dictionary wraps BsonDocument and implements
IDictionary. It works as a hashtable where keys are case sensitive strings and values are convenient .NET types.
Useful members:
$dictionary.Count
$dictionary.Contains('key')
$dictionary.Add('key', ..)
$dictionary.Remove('key')
$dictionary.Clear()
Setting values:
$dictionary['key'] = ..
$dictionary.key = ..
Getting values:
.. = $dictionary['key']
.. = $dictionary.key
NOTE: On getting values, `$dictionary.key` fails if the key is missing in the strict mode. Use Contains() in order
to check for missing keys. Or get values using `$dictionary['key']`, it returns nulls for missing keys.
PARAMETERS
-InputObject
Specifies the object to be converted to Mdbc.Dictionary. Suitable objects are dictionaries, PowerShell custom
objects, and complex .NET types.
If the input object is omitted or null then an empty document is created.
Required? false
Position? 0
Default value
Accept pipeline input? true (ByValue)
Accept wildcard characters?
-Convert
A script called on conversion of unknown data types. The variable $_ represents the unknown object. The script
returns a new object suitable for conversion.
Examples: {} converts unknown data to nulls. {"$_"} converts data to strings.
Converters should be used sparingly, normally with unknown or varying data.
Required? false
Position? named
Default value
Accept pipeline input?
Accept wildcard characters?
-Id
Specifies the _id value of result document, either literally or using a script block returning this value for
the input object represented by the variable $_. The script block is used for multiple objects in the pipeline.
If Id is used then _id must not exist in input objects or Property.
Required? false
Position? named
Default value
Accept pipeline input?
Accept wildcard characters?
-NewId
Tells to assign _id to a new generated MongoDB.Bson.ObjectId.
If NewId is used then _id must not exist in input objects or Property.
Required? false
Position? named
Default value
Accept pipeline input?
Accept wildcard characters?
-Property
Specifies properties or keys which values are included into documents or defines calculated fields. Missing
input properties and keys are ignored.
If Property is omitted then types registered by Register-MdbcClassMap are serialized. Use `-Property *` in
order to convert by properties instead.
Arguments:
1. Strings define property or key names of input objects. Wildcards are not supported but "*" may be used in
order to tell "convert all properties".
2. Hashtables @{Key=Value} define renamed and calculated fields. The key is the result document field name.
The value is either a string (input object property or key) or a script block (field value calculated from the
input object $_).
3. Hashtables @{Name=...; Expression=...} or @{Label=...; Expression=...} are similar but follow the syntax of
`Select-Object -Property`.
See New-MdbcData examples.
Required? false
Position? named
Default value
Accept pipeline input?
Accept wildcard characters?
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer, PipelineVariable, and OutVariable. For more information, see
about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).
INPUTS
[Mdbc.Dictionary]
Objects created by New-MdbcData or obtained by Get-MdbcData or Import-MdbcData. This type is the most
effective and safe as input/output of Mdbc data cmdlets.
[IDictionary]
Hashtables and other dictionaries are converted to new documents. Keys are strings used as field names. Nested
collections, dictionaries, and custom objects are converted to BSON documents and collections recursively.
Other values are converted to BSON values.
[PSObject]
Objects are converted to new documents. Property names are used as field names. Nested collections,
dictionaries, and custom objects are converted to BSON documents and collections recursively. Other values are
converted to BSON values.
$null
Null is converted to an empty document by New-MdbcData and ignored by Add-MdbcData and Export-MdbcData.
OUTPUTS
[Mdbc.Dictionary]
PowerShell friendly BsonDocument wrapper.
-------------------------- EXAMPLE 1 --------------------------
# How to create empty documents
New-MdbcData
New-Object Mdbc.Dictionary
[Mdbc.Dictionary]::new() # PowerShell v5
# How to create documents with specified _id
New-MdbcData -Id 42
# How to create documents with generated _id
New-MdbcData -NewId
-------------------------- EXAMPLE 2 --------------------------
# Connect collection
Import-Module Mdbc
Connect-Mdbc . test test -NewCollection
# Create a new document, set some data
$data = New-MdbcData -Id 12345
$data.Text = 'Hello world'
$data.Date = Get-Date
# Add the document to the database
$data | Add-MdbcData
# Query the document from the database
$result = Get-MdbcData @{_id = 12345}
$result
-------------------------- EXAMPLE 3 --------------------------
# Connect collection
Import-Module Mdbc
Connect-Mdbc . test test -NewCollection
# Create data from input objects and add to the database
# (Note: in similar cases Add-MdbcData may be used alone)
Get-Process mongod |
New-MdbcData -Id {$_.Id} -Property Name, WorkingSet, StartTime |
Add-MdbcData
# Query the data
$result = Get-MdbcData
$result
-------------------------- EXAMPLE 4 --------------------------
# Example of various forms of property expressions.
# Note that ExitCode throws, so that Code will be null.
New-MdbcData (Get-Process -Id $Pid) -Property `
Name, # existing property name
Missing, # missing property name is ignored
@{WS1 = 'WS'}, # @{name = old name} - renamed property
@{WS2 = {$_.WS}}, # @{name = scriptblock} - calculated field
@{Ignored = 'Missing'}, # renaming of a missing property is ignored
@{n = '_id'; e = 'Id'}, # @{name=...; expression=...} like Select-Object does
@{l = 'Code'; e = 'ExitCode'} # @{label=...; expression=...} another like Select-Object
RELATED LINKS
Add-MdbcData
Export-MdbcData
SYNOPSIS
Creates data documents.
SYNTAX
New-MdbcData [[-InputObject] <PSObject>] [-Convert <ScriptBlock>] [-Id <PSObject>] [-Property <Object[]>] [-NewId]
[<CommonParameters>]
DESCRIPTION
This command is used to create Mdbc.Dictionary documents. Input objects come from the pipeline or as the parameter.
Created documents are used by other module commands. Note that Add-MdbcData and Export-MdbcData also have
parameters Id, NewId, Convert, Property for making documents from input objects, so that in some cases
intermediate use of New-MdbcData is not needed.
Result documents are returned as Mdbc.Dictionary objects. Mdbc.Dictionary wraps BsonDocument and implements
IDictionary. It works as a hashtable where keys are case sensitive strings and values are convenient .NET types.
Useful members:
$dictionary.Count
$dictionary.Contains('key')
$dictionary.Add('key', ..)
$dictionary.Remove('key')
$dictionary.Clear()
Setting values:
$dictionary['key'] = ..
$dictionary.key = ..
Getting values:
.. = $dictionary['key']
.. = $dictionary.key
NOTE: On getting values, `$dictionary.key` fails if the key is missing in the strict mode. Use Contains() in order
to check for missing keys. Or get values using `$dictionary['key']`, it returns nulls for missing keys.
PARAMETERS
-InputObject
Specifies the object to be converted to Mdbc.Dictionary. Suitable objects are dictionaries, PowerShell custom
objects, and complex .NET types.
If the input object is omitted or null then an empty document is created.
Required? false
Position? 0
Default value
Accept pipeline input? true (ByValue)
Accept wildcard characters?
-Convert
A script called on conversion of unknown data types. The variable $_ represents the unknown object. The script
returns a new object suitable for conversion.
Examples: {} converts unknown data to nulls. {"$_"} converts data to strings.
Converters should be used sparingly, normally with unknown or varying data.
Required? false
Position? named
Default value
Accept pipeline input?
Accept wildcard characters?
-Id
Specifies the _id value of result document, either literally or using a script block returning this value for
the input object represented by the variable $_. The script block is used for multiple objects in the pipeline.
If Id is used then _id must not exist in input objects or Property.
Required? false
Position? named
Default value
Accept pipeline input?
Accept wildcard characters?
-NewId
Tells to assign _id to a new generated MongoDB.Bson.ObjectId.
If NewId is used then _id must not exist in input objects or Property.
Required? false
Position? named
Default value
Accept pipeline input?
Accept wildcard characters?
-Property
Specifies properties or keys which values are included into documents or defines calculated fields. Missing
input properties and keys are ignored.
If Property is omitted then types registered by Register-MdbcClassMap are serialized. Use `-Property *` in
order to convert by properties instead.
Arguments:
1. Strings define property or key names of input objects. Wildcards are not supported but "*" may be used in
order to tell "convert all properties".
2. Hashtables @{Key=Value} define renamed and calculated fields. The key is the result document field name.
The value is either a string (input object property or key) or a script block (field value calculated from the
input object $_).
3. Hashtables @{Name=...; Expression=...} or @{Label=...; Expression=...} are similar but follow the syntax of
`Select-Object -Property`.
See New-MdbcData examples.
Required? false
Position? named
Default value
Accept pipeline input?
Accept wildcard characters?
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer, PipelineVariable, and OutVariable. For more information, see
about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).
INPUTS
[Mdbc.Dictionary]
Objects created by New-MdbcData or obtained by Get-MdbcData or Import-MdbcData. This type is the most
effective and safe as input/output of Mdbc data cmdlets.
[IDictionary]
Hashtables and other dictionaries are converted to new documents. Keys are strings used as field names. Nested
collections, dictionaries, and custom objects are converted to BSON documents and collections recursively.
Other values are converted to BSON values.
[PSObject]
Objects are converted to new documents. Property names are used as field names. Nested collections,
dictionaries, and custom objects are converted to BSON documents and collections recursively. Other values are
converted to BSON values.
$null
Null is converted to an empty document by New-MdbcData and ignored by Add-MdbcData and Export-MdbcData.
OUTPUTS
[Mdbc.Dictionary]
PowerShell friendly BsonDocument wrapper.
-------------------------- EXAMPLE 1 --------------------------
# How to create empty documents
New-MdbcData
New-Object Mdbc.Dictionary
[Mdbc.Dictionary]::new() # PowerShell v5
# How to create documents with specified _id
New-MdbcData -Id 42
# How to create documents with generated _id
New-MdbcData -NewId
-------------------------- EXAMPLE 2 --------------------------
# Connect collection
Import-Module Mdbc
Connect-Mdbc . test test -NewCollection
# Create a new document, set some data
$data = New-MdbcData -Id 12345
$data.Text = 'Hello world'
$data.Date = Get-Date
# Add the document to the database
$data | Add-MdbcData
# Query the document from the database
$result = Get-MdbcData @{_id = 12345}
$result
-------------------------- EXAMPLE 3 --------------------------
# Connect collection
Import-Module Mdbc
Connect-Mdbc . test test -NewCollection
# Create data from input objects and add to the database
# (Note: in similar cases Add-MdbcData may be used alone)
Get-Process mongod |
New-MdbcData -Id {$_.Id} -Property Name, WorkingSet, StartTime |
Add-MdbcData
# Query the data
$result = Get-MdbcData
$result
-------------------------- EXAMPLE 4 --------------------------
# Example of various forms of property expressions.
# Note that ExitCode throws, so that Code will be null.
New-MdbcData (Get-Process -Id $Pid) -Property `
Name, # existing property name
Missing, # missing property name is ignored
@{WS1 = 'WS'}, # @{name = old name} - renamed property
@{WS2 = {$_.WS}}, # @{name = scriptblock} - calculated field
@{Ignored = 'Missing'}, # renaming of a missing property is ignored
@{n = '_id'; e = 'Id'}, # @{name=...; expression=...} like Select-Object does
@{l = 'Code'; e = 'ExitCode'} # @{label=...; expression=...} another like Select-Object
RELATED LINKS
Add-MdbcData
Export-MdbcData