{"id":13393743,"url":"https://github.com/alpacahq/marketstore","last_synced_at":"2025-05-15T01:09:00.657Z","repository":{"id":28167420,"uuid":"116546320","full_name":"alpacahq/marketstore","owner":"alpacahq","description":"DataFrame Server for Financial Timeseries Data","archived":false,"fork":false,"pushed_at":"2024-05-11T09:43:55.000Z","size":7350,"stargazers_count":1924,"open_issues_count":75,"forks_count":236,"subscribers_count":109,"default_branch":"master","last_synced_at":"2025-04-13T23:53:43.394Z","etag":null,"topics":["alpaca","binance","bitmex","cryptocurrency","database","financial-analysis","financial-timeseries-data","gdax","golang","hdf5-files","marketstore","pandas-dataframe","time-series","timeseries-database","trading"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alpacahq.png","metadata":{"files":{"readme":"README.ja.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-01-07T07:27:25.000Z","updated_at":"2025-04-12T05:00:40.000Z","dependencies_parsed_at":"2024-06-18T18:33:09.128Z","dependency_job_id":"711526a7-79c5-4769-a4e9-368209ee650d","html_url":"https://github.com/alpacahq/marketstore","commit_stats":{"total_commits":702,"total_committers":34,"mean_commits":"20.647058823529413","dds":0.6239316239316239,"last_synced_commit":"007586568aa92a1c83189b3c06843dc27a23e5b3"},"previous_names":[],"tags_count":85,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alpacahq%2Fmarketstore","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alpacahq%2Fmarketstore/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alpacahq%2Fmarketstore/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alpacahq%2Fmarketstore/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alpacahq","download_url":"https://codeload.github.com/alpacahq/marketstore/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254254042,"owners_count":22039792,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alpaca","binance","bitmex","cryptocurrency","database","financial-analysis","financial-timeseries-data","gdax","golang","hdf5-files","marketstore","pandas-dataframe","time-series","timeseries-database","trading"],"created_at":"2024-07-30T17:00:59.655Z","updated_at":"2025-05-15T01:08:55.648Z","avatar_url":"https://github.com/alpacahq.png","language":"Go","funding_links":[],"categories":["Go","Databases","Financial Big Data","Golang"],"sub_categories":["Cryptocurrencies","TimeSeries Analysis","Data Source","Data Visualization"],"readme":"# MarketStore\n## Introduction\nMarketStoreはファイナンスにおける時系列データに特化したデータベースサーバです。\nスケーラビリティについて十分に考慮されており、あなたのシステムのあらゆるところからアクセス可能で、かつ拡張可能なDataFrameサービスとして使用することができます。\n\n\n膨大な金融市場データの扱いにおいて問題となるスケーラビリティを確保するために、MarketStoreはゼロベースから設計されています。アルゴリズム取引におけるバックテストやチャート作成, 何年間にもわたるデータからなる価格履歴をTick(株式、債権、為替などの金融商品における価格変化の最小単位)レベルの粒度で扱うことができます。\n米国株式や暗号通貨の分野を主な対象として扱っています。\n\nもしあなたが大量のHDF5ファイルの扱いに苦しんでいるのであれば、MarketStoreはその完璧な解決策となるでしょう。\n\nインストールしていただくことで入る機能に加えて、GDAXから取得した暗号通貨の価格データを用いてDBに書き込みを行うなど、プラグイン設定も簡単に使うことができます。\n\nMarketStoreを使うことで、ネットワーク越しであってもローカルディスクにあるHDF5ファイルに対して行うのと同じくらい低いレイテンシでDataFrameに対してクエリをかけることができます。新規データの書き込みであれば、DataFrameの100倍以上の速度が見込めます。これはストレージの形式を特定のデータのタイプやユースケースに最適化しており、また最近のファイルシステム/ハードウェアの特性を考慮した上でMarketStoreが設計されているためです。\n\nMarketStoreは本番環境で使っていただける品質になっています。すでにAlpacaでは重要なビジネス向けに何年も使用を重ねてきています。\nもしバグを発見したり、MarketStoreに興味がある方は開発にご協力いただければと思います。\n\n\n## Install\n\n### Docker\nすぐにMarketStoreを使ってみたい場合は、最新の [docker image](https://hub.docker.com/r/alpacamarkets/marketstore/tags/) を使ってDBインスタンスを生成する方法をおすすめします。 デフォルトの mkts.yml (設定ファイル)もあり、 `/data` をデータ保存先のルートディレクトリとして定義された状態でコンテナを起動できます。 デフォルト設定でコンテナを立ち上げる場合は以下のコマンドを実行してください。\n``` sh\ndocker run -i -p 5993:5993 alpacamarkets/marketstore:latest\n```\n\n自分でカスタマイズした設定ファイル `mkts.yml` でインスタンスを起動したい場合は、 \n下記のような手順で自分で新しいコンテナを作って、その中に設定ファイルを埋め込んでください。\n``` sh\ndocker create --name mktsdb -p 5993:5993 alpacamarkets/marketstore:latest\ndocker cp mkts.yml mktsdb:/etc/mkts.yml\ndocker start -i mktsdb\n```\n\n起動中のDockerコンテナに対してセッションを張る場合は以下のようにしてください。\n``` sh\nmarketstore connect --url localhost:5993\n```\n\n### Source\nMarketStoreはGoを用いて実装されているので、`go install`コマンドでインストールすることができます。\n```sh\ngo install github.com/alpacahq/marketstore/v4@latest\n# export GOROOT=$HOME/go\n# export PATH=$PATH:$GOROOT/bin\nmarketstore --version\n```\n\nソースコードからビルドすることも簡単です。Go `1.11` 以上のバージョンを使用し、また依存管理には`go mod` を使用しています。\n``` sh\ngo get -u github.com/alpacahq/marketstore\n```\n以下でバイナリをコンパイル＆インストールしてください。\n``` sh\nmake install\n```\n必須ではありませんが、本リポジトリに付属しているプラグインをインストールすることも簡単にできます。\n``` sh\nmake plugins\n```\n\n## Usage\n`marketstore` コマンドで、使用することができるコマンド一覧が得られます。\n```\nmarketstore\n```\n$GOPATHの設定によってはこちら\n```\n$GOPATH/bin/marketstore\n```\n\n`mkts.yml` という名前で設定ファイルを独自に定義することができますが、デフォルトの設定ファイルであればコマンドで生成することもできます。 \n```\n$GOPATH/bin/marketstore init\n```\nMarketStoreを起動します。\n```\n$GOPATH/bin/marketstore start\n```\n\n以下のような出力が得られたら起動成功です。\n```\nexample@alpaca:~/go/bin/src/github.com/alpacahq/marketstore$ marketstore\nI0619 16:29:30.102101    7835 log.go:14] Disabling \"enable_last_known\" feature until it is fixed...\nI0619 16:29:30.102980    7835 log.go:14] Initializing MarketStore...\nI0619 16:29:30.103092    7835 log.go:14] WAL Setup: initCatalog true, initWALCache true, backgroundSync true, WALBypass false:\nI0619 16:29:30.103179    7835 log.go:14] Root Directory: /example/go/bin/src/github.com/alpacahq/marketstore/project/data/mktsdb\nI0619 16:29:30.144461    7835 log.go:14] My WALFILE: WALFile.1529450970104303654.walfile\nI0619 16:29:30.144486    7835 log.go:14] Found a WALFILE: WALFile.1529450306968096708.walfile, entering replay...\nI0619 16:29:30.244778    7835 log.go:14] Beginning WAL Replay\nI0619 16:29:30.244861    7835 log.go:14] Partial Read\nI0619 16:29:30.244882    7835 log.go:14] Entering replay of TGData\nI0619 16:29:30.244903    7835 log.go:14] Replay of WAL file /example/go/bin/src/github.com/alpacahq/marketstore/project/data/mktsdb/WALFile.1529450306968096708.walfile finished\nI0619 16:29:30.289401    7835 log.go:14] Finished replay of TGData\nI0619 16:29:30.340760    7835 log.go:14] Launching rpc data server...\nI0619 16:29:30.340792    7835 log.go:14] Initializing websocket...\nI0619 16:29:30.340814    7835 plugins.go:14] InitializeTriggers\nI0619 16:29:30.340824    7835 plugins.go:42] InitializeBgWorkers\n```\n\n## Configuration\nMarketStoreを実行するにはYAMLで書かれた設定ファイル `mkts.yml` が必要になります。`marketstore init` コマンドでデフォルトを生成できます。設定ファイルのパスは `marketstore start --config [設定ファイルへのパス]` という形で `--config` オプションで指定してください。指定されなかった場合は、marketstoreが実行されたパス内から`mkts.yml`を探します。\n\n### 設定項目\nVar | Type | Description\n--- | --- | ---\nroot_directory | string |  MarketStore データベースが使用するディレクトリ\nlisten_port | int | MarketStoreがJSON-RPC APIに使用するポート番号\ngrpc_listen_port | int | MarketStoreがGRPC APIに使用するポート番号\ntimezone | string |  タイムゾーン. `TZ` に定義されている値 (例 America/New_York)\nlog_level | string  | 出力する最低ログレベル `(info | warning | error)`\nstop_grace_period | int | SIGINT シグナルを受信してから終了するまでに待つ時間\nwal_rotate_interval | int | ディスクにフラッシュしてWALファイルがトリムされる頻度[分]\nstale_threshold | int | MarketStoreがシンボルを古いものと認識するしきい値[日]\ntriggers | slice | triggerプラグインのリスト\nbgworkers | slice | background workerプラグインのリスト\n\n### デフォルト設定(mkts.yml)\n```\nroot_directory: data\nlisten_port: 5993\ngrpc_listen_port: 5995\nlog_level: info\nstop_grace_period: 0\nwal_rotate_interval: 5\nstale_threshold: 5\n```\n\n\n## Clients\nMarketStoreインスタンスが起動したあとは、Tickデータを読み書きし始めることができます。\n\n### Python\n[pymarketstore](https://github.com/alpacahq/pymarketstore) が標準のPythonクライアントになっています。すでにMarketStoreが起動していることを確認の上、ご使用ください。\n\n```\nIn [1]: import pymarketstore as pymkts\n\n## query (データの参照)\n\nIn [2]: param = pymkts.Params('BTC', '1Min', 'OHLCV', limit=10)\n\nIn [3]: cli = pymkts.Client()\n\nIn [4]: reply = cli.query(param)\n\nIn [5]: reply.first().df()\nOut[5]:\n                               Open      High       Low     Close     Volume\nEpoch\n2018-01-17 17:19:00+00:00  10400.00  10400.25  10315.00  10337.25   7.772154\n2018-01-17 17:20:00+00:00  10328.22  10359.00  10328.22  10337.00  14.206040\n2018-01-17 17:21:00+00:00  10337.01  10337.01  10180.01  10192.15   7.906481\n2018-01-17 17:22:00+00:00  10199.99  10200.00  10129.88  10160.08  28.119562\n2018-01-17 17:23:00+00:00  10140.01  10161.00  10115.00  10115.01  11.283704\n2018-01-17 17:24:00+00:00  10115.00  10194.99  10102.35  10194.99  10.617131\n2018-01-17 17:25:00+00:00  10194.99  10240.00  10194.98  10220.00   8.586766\n2018-01-17 17:26:00+00:00  10210.02  10210.02  10101.00  10138.00   6.616969\n2018-01-17 17:27:00+00:00  10137.99  10138.00  10108.76  10124.94   9.962978\n2018-01-17 17:28:00+00:00  10124.95  10142.39  10124.94  10142.39   2.262249\n\n## write (データの書き込み)\n\nIn [7]: import numpy as np\n\nIn [8]: import pandas as pd\n\nIn [9]: data = np.array([(pd.Timestamp('2017-01-01 00:00').value / 10**9, 10.0)], dtype=[('Epoch', 'i8'), ('Ask', 'f4')])\n\nIn [10]: cli.write(data, 'TEST/1Min/Tick')\nOut[10]: {'responses': None}\n\nIn [11]: cli.query(pymkts.Params('TEST', '1Min', 'Tick')).first().df()\nOut[11]:\n                            Ask\nEpoch\n2017-01-01 00:00:00+00:00  10.0\n\n```\n\n* 可変長レコード \n  \nmarketstoreは一つのtimeframe(時間幅)に存在するレコード数を1つに絞ることで高速化を実現しているデータベースで、\n同じtimeframeに対するレコードの書き込みは基本的に上書きされます。\n`1D`(1日)から`1Sec`(1秒)までのtimeframeに対応しており、\nデータの頻度に応じてより長い時間幅を指定していただくことで、より高速に読み書きを行うことができます。\n\nしかし、板情報やTICKデータなど、特定のtimeframeごとにデータが到着しなかったり、\n1秒よりも更に頻繁に到着するデータの保存にも対応しています。\n特定のtimeframeに複数のレコードを書き込むことができる機能として、\nこれをvariable-length(可変長)レコード機能と呼んでいます。\n\npymarketstoreで該当バケットへのwriteを行う際に`isvariablelength=True` を指定していただくことで、\n該当のバケットの特定timeframeへ複数レコードを書き込むことができ、\n1秒ごとよりも速い間隔で届くTICKデータ等を読み書きする際に活用できます。\n\n```python\nimport numpy as np, pandas as pd, pymarketstore as pymkts\n\nsymbol, timeframe, attribute_group = \"TEST\", \"1Sec\", \"Tick\"\ndata_type = [('Epoch', 'i8'), ('Bid', 'f4'), ('Ask', 'f4'), ('Nanoseconds', 'i4')]\ntbk = \"{}/{}/{}\".format(symbol, timeframe, attribute_group)\nclient = pymkts.Client()\n\n# --- write variable length records\ndata = np.array([\n    (pd.Timestamp('2021-01-01 00:00:00').value / 10 ** 9, 10.0, 20.0, 1000000),\n    (pd.Timestamp('2021-01-01 00:00:00').value / 10 ** 9, 30.0, 40.0, 2000000),\n    (pd.Timestamp('2021-01-01 00:00:00').value / 10 ** 9, 50.0, 60.0, 3000000),\n], dtype=data_type)\nclient.write(data, tbk, isvariablelength=True)\n\n# --- query variable length records\nparams = pymkts.Params(symbol, timeframe, attribute_group)\nprint(client.query(params=params).first().df())\n\n# --- tearDown\nclient.destroy(tbk)\n```\nshows\n```\n                            Bid   Ask  Nanoseconds\nEpoch                                             \n2021-01-01 00:00:00+00:00  10.0  20.0      1000000\n2021-01-01 00:00:00+00:00  30.0  40.0      2000000\n2021-01-01 00:00:00+00:00  50.0  60.0      3000000\n```\n\nmarketstoreではレコードの時刻は常に`Epoch`カラム、'i8'(int64)のエポック秒で表現される作りになっており、\nこれは1秒より細かい精度まで時刻情報を保存するには十分なデータサイズではありません。\nそのためmarketstoreでは別の`Nanoseconds`('i4'データタイプ)に1秒以下の情報を保存することで可変長レコード機能を実現しています。\n\n### Command-line\nmarketstoreインスタンスに接続するコマンドはこちらです。\n```\n// For a local db-\nmarketstore connect --dir \u003cpath\u003e\n// For a server-\nmarketstore connect --url \u003caddress\u003e\n```\n接続後はsqlセッションを通じてコマンドを実行することができます。\n\n## Plugins\nGoにおけるプラグインは Go 1.10以上(Linux)で最適に動きます。プラグインについての詳細は [plugins package](./plugins/) をご覧ください。\nここでは特に取り上げたいいくつかのプラグインについてご紹介します。\n\n### Streaming\nWebSocketのストリームを利用してリアルタイムでアップデートを受け取ることができます。\n`/ws` でWebSocket接続を受けつけることができ、データをPushすることもできます。\n詳細については [the package](./contrib/stream/) をご参照ください。\n\n### GDAX Data Feeder\n[GDAX](https://docs.gdax.com/#get-historic-rates) から暗号通貨のデータを取得することができます。\nMarketStoreをインストールすると、すぐにDataFrame型の情報をqueryして取得することができます。ネットワーク越しであっても、ローカルディスク上のHDF5ファイルを読み込むのと同じくらい低いレイテンシで扱うことができますし、最後尾にデータを追加する処理はDataFrameで行う100倍も速いはずです。MarketStoreはストレージの形式を特定のデータ型、ユースケース、またファイルシステムやハードウェアの特性に最適化した形で設計されているためです。\n\ndata pollerを設定してGDAXからデータを取得しはじめましょう。\n詳細については [the package](./contrib/gdaxfeeder/) をご参照ください。\n\n### On-Disk Aggregation\nこのプラグインを使うと、 tick/分 レベルのデータだけを気にすればよくなります。時系列ベースでディスク上のデータのアグリゲーションをしてくれるプラグインです。詳しくは\n[the package](./contrib/ondiskagg/)をご参照ください。\n\n## Replication\nmarketstoreはmasterからreplicaへのレプリケーションをサポートしています。\n`mkts.yml` に以下の設定を追記することで、データのレプリケーションを有効化できます。\n\n- master instance\n```\nreplication:\n  # when enabled=true, this instance works as master instance and accept connections from replicas\n  enabled: true\n  # when tls_enabled=true, transport security between master and replica is enabled.\n  # tls_enabled: true # both master and replica should have tls_enabled=true to enable TLS\n  # public/private key pair from a pair of files. The files must contain PEM encoded data.\n  # The cert file may contain intermediate certificates following the leaf certificate to form a certificate chain.\n  # cert_file: \"/absolute/path/to/server.crt\" # both master and replica should have this config to enable TLS\n  # key_file: \"/absolute/path/to/server.key\"\n  # port to be used for the replication protocol\n  listen_port: 5996\n```\n\n- replica instance(s)\n```\nreplication:\n  # when master_host is set, this instance works as a replica instance\n  master_host: \"127.0.0.1:5995\"\n  # when tls_enabled=true on master server, GRPC communication between master and replica is encrypted by SSL.\n  # tls_enabled: true\n  # cert_file: \"/absolute/path/to/server.crt\" # both master and replica should have this config to enable TLS\n\n```\n\n## 開発に協力していただける方へ\n興味がある方はぜひMarketStoreの開発にご協力ください！\nGithubのIssue報告やPullRequestでも構いませんし、`oss@alpaca.markets` に直接ご連絡いただいても構いません。 \nPull Requestを作る際は、下記のコマンドを実行してテストが通る状態であることをご確認ください。\n\n``` sh\nmake unittest\n```\n\n### プラグイン開発\n我々の取り組む分野に対する要求は多岐に渡るため、MarketStoreは柔軟にプラグインを追加できるアーキテクチャをとっています。\n独自のプラグインを生成したい方は [plugins](./plugins/) をご覧ください。\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falpacahq%2Fmarketstore","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falpacahq%2Fmarketstore","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falpacahq%2Fmarketstore/lists"}