README
compass-aggregations
Compass Plugin for the MongoDB Aggregation Pipeline Builder.
Code Tour
src/components/aggregations
The primary export is connected componentsrc/modules/
is where action happens- action creators components call
- reducers that call dataService, window.open, emit to other plugins, etc.
- follows the
ducks
pattern
src/stores/store
is where plugin listens+responds to events of interest from other plugins- store is global state instantiated via
configureStore()
- All tests are local to their module e.g.
src/*/<module>.spec.js
Note: Cross-plugin Communication
How does clicking on export to language button in aggregation builder show the modal that has code in it?
The aggregation builder in Compass actually involves 2 Compass plugins:
<Aggregation />
Plugin for primary UI<ExportToLanguage />
Modal plugin that connects<Aggregation />
tobson-transpilers
for actual compiling to another language
Here's how these 2 plugins come together:
./src/modules/export-to-language.js
appRegistry.emit('open-aggregation-export-to-language', generatePipelineAsString())
compass-export-to-language/src/stores/store.js
Listener for 'export to lang' event via appRegistry and renders its modal.compass-export-to-language/src/modules/export-query.js
has reducer for callingbson-transpilers.compile()
which populates the code in the modal dialog.
mongodb-data-service
Provider
Usage with a See ./examples-data-service-provider.js
for details on what data-service
functions are used and the applicable options for each.
Contributing
If you're interested in helping with the Aggregation Builder plugin, we'd be over the moon excited! Here are a few ideas if you're interested but not sure where to start:
- Add a new example aggregation
- Additions/clarifications/improvements to
README
's - More tests (especially edge cases!)
- Generate
jsdoc
html to include in GitHub pages - Improve build times (e.g. audit our webpack configs)
Related
<ExportToLanguage />
Modal plugin that connects<Aggregation />
tobson-transpilers
for actual compiling to another languagemongodb-js/stage-validator
Aggregation Pipeline Stage grammar.bson-transpilers
Read the amazing: Compiler in JavaScript using ANTLRmongodb-js/ace-mode
MongoDB highlighting rules for ACE.mongodb-js/ace-theme
MongoDB syntax highlighting rules for ACE.mongodb-js/ace-autocompleter
Makes ACE autocompletion aware of MongoDB Aggregation Pipeline operators, expressions, and fields.
Usage
This plugin uses an instance of a Redux store and not the traditional singleton, so the store instance must be passed to the plugin. The plugin exports a function to initialise the store instance, which decorates it with various methods to conveniently set any values it uses.
This is for:
@mongodb-js/compass-aggregations 4.0.0-beta.11
@mongodb-js/compass-export-to-language 4.0.2
Browser
Setting values via configure:
import AppRegistry from 'hadron-app-registry';
import AggregationsPlugin, {
configureStore as configureAggregationsStore
} from '@mongodb-js/compass-aggregations';
import ExportToLanguagePlugin, {
configureStore as configureExportToLanguageStore
} from '@mongodb-js/compass-export-to-language';
const handleOut = (namespace) => {
window.open(`https://cloud.mongodb.com/${namespace}`, '_new');
};
const handleCopy = (query) => {
alert(query);
};
const appRegistry = new AppRegistry();
const aggregationsStore = configureAggregationsStore({
dataProvider: {
error: null,
dataProvider: dataProvider
},
namespace: 'db.coll',
serverVersion: '4.2.0',
fields: [],
isAtlasDeployed: true,
allowWrites: false,
outResultsFn: handleOut,
env: 'atlas',
localAppRegistry: appRegistry
});
const exportToLanguageStore = configureExportToLanguageStore({
localAppRegistry: appRegistry,
copyToClipboardFn: handleCopy
});
<AggregationsPlugin store={aggregationsStore} />
<ExportToLanguagePlugin store={exportToLanguageStore} />
Hadron/Electron
const role = appRegistry.getRole('Collection.Tab')[0];
const Plugin = role.component;
const configureStore = role.configureStore;
const store = configureStore({
globalAppRegistry: appRegistry,
localAppRegistry: localAppRegistry,
dataProvider: {
error: null,
dataProvider: dataProvider
},
env: 'on-prem',
namespace: 'db.coll',
serverVersion: '4.2.0',
fields: []
});
<Plugin store={store} />
Fields
The fields array must be an array of objects that the ACE editor autocompleter understands. See This example for what that array looks like.
Data Provider
The data provider is an object that must adhere to the following interface:
/**
* Get a count of documents.
*
* @param {String} namespace - The namespace in "db.collection" format.
* @param {Object} filter - The MQL query filter.
* @param {Object} options - The query options.
* @param {Function} callback - Gets error and integer count as params.
*/
provider.count(namespace, filter, options, callback);
/**
* Execute an aggregation pipeline.
*
* @param {String} namespace - The namespace in "db.collection" format.
* @param {Array} pipeline - The pipeline.
* @param {Object} options - The agg options.
* @param {Function} callback - Gets error and cursor as params. Cursor must
* implement #toArray (which takes a callback with error and an array of result docs)
* and #close
*/
provider.aggregate(namespace, pipeline, options, callback);
App Registry Events Emmitted
Various actions within this plugin will emit events for other parts of the
application can be listened to via hadron-app-registry.
Local
events are scoped to a Tab
.
Global
events are scoped to the whole Compass application.
Global
- 'open-create-view': Indicated
Create View
is to be opened. - 'compass:export-to-language:opened', source: Indicates
export-to-language
was opened.source
refers to the module it is opened from, in this caseAggregations
. - 'compass:aggregations:pipeline-imported': Indicates a pipeline ws imported, either from pasting the pipeline in, or from using the import functionality. Sends data to metrics.
- 'compass:aggregations:create-view', numOfStages: Indicates
Create View
was successful.numOfStages
refers to pipeline length. Sends data to metrics. - 'compass:aggregations:pipeline-opened': Indicates a saved pipeline was opened. Sends pipeline data to metrics.
- 'open-namespace-in-new-tab': Indicates current pipeline's namespace is to
be opened in a new tab. Called when
Create View
is successful, when$merge
are to be shown, when$out
results are to be shown. - 'compass:aggregations:update-view', numOfStages: Indicates a pipeline view
was updated.
numOfStages
refers to the length of the pipeline. Sends data to metrics. - 'compass:aggregations:settings-applied', settings: Indicates pipeline
settings are to be applied.
settings
include:isExpanded
,isCommentMode
,isDirty
,sampleSize
,maxTimeMS
,limit
. - 'refresh-data': Indicates a data refresh is required within Compass.
- 'select-namespace', metadata: Indicates a namespace is being selected.
Emitted when updating a collection.
metadata
refers to information about the pipeline. - 'agg-pipeline-deleted': Indicates a pipeline was deleted. Sends pipeline data to metrics.
- 'agg-pipeline-saved', pipelineName: Indicates a pipeline was saved locally. Sens pipeline data to analytics.
- 'agg-pipeline-executed', metadata: Indicates a pipeline was executed.
metadata
refers to data about the pipeline. Sends pipeline data to metrics. - 'agg-pipeline-out-executed', pipelineId: Indicates a pipeline was executed
with a
$out
. Sends pipeline data to metrics.
Local
- 'open-aggregation-export-to-language', pipeline: Indicates
export-to-language
plugin is to opened.pipeline
refers to the pipeline to be exported. - 'open-create-view', { meta: { source, pipeline }}: Indicates
Create View
is being opened.
App Registry Events Received
Local
- 'import-finished': When import data was successful, refresh plugin's input data.
- 'fields-changed', fields: Received when schema fields change. Updates plugin's fields.
- 'refresh-data': Received when Compass data was refreshed. Refreshes input data in the plugin.
- 'open-create-view', { meta: { source, pipeline }}: Received when
Create View
is to be opened. Opens a Create View modal.
Global
- 'refresh-data': Received when Input data is to be refreshed on Compass level. Refreshes plugin's input.
Metrics Events
refresh-data
open-create-view
agg-pipeline-saved
agg-pipeline-deleted
agg-pipeline-executed
agg-pipeline-out-executed
compass:aggregations:update-view
compass:aggregations:create-view
compass:aggregations:pipeline-opened
compass:aggregations:settings-applied
compass:aggregations:pipeline-imported
Development
Tests
npm run test
Electron
npm start
Analyze Build
npm run analyze
Install
npm i -S @mongodb-js/compass-aggregations